Skip to content

Latest commit

 

History

History
295 lines (227 loc) · 14.6 KB

reference_style_guide.md

File metadata and controls

295 lines (227 loc) · 14.6 KB
Raw

SCRF Writing Style Guide

The Smart Contract Research Forum (SCRF) Writing Style Guide summarizes the standards and best practices writers should follow when adding to Community Development resources.

Table of Contents

Principles and Intent

The SCRF Style Guide should be used to write clear and consistent content across teams and channels regardless of whether the writer is internal or external. Please use this as a reference guide when writing for SCRF. With every piece of content, aim to:

  • Educate: Give readers the exact information they need to know while breaking down concepts into the simplest terms possible. The writer is considered to be the expert educating the reader who may not have access to the same background information.
  • Provide Value: The writer should understand the topic and use simple words and sentences. Before writing, ask: What purpose does this serve? Who is going to read it? What do they need to know?
  • Be Open and Respectful: Treat readers with the respect they deserve. Remember they are busy, coming from everywhere, and with varied backgrounds. At SCRF, we want to inform while being considerate, impartial, and inclusive.

Voice and Tone

SCRF materials should cater to readers who are unfamiliar with the SCRF system. Writers should assume that their readers have tight schedules and short attention spans. As such, writers should focus on communicating concepts as clearly and succinctly as possible. At SCRF, we want to speak like experienced yet respectful academics at the cutting edge of research.

Style tips:

  • Use simple language.
  • Use short, concise sentences.
  • Avoid unnecessary words.
  • Remain open and objective.
  • Provide examples when possible.
  • Provide examples to help explain concepts, but avoid complicating them.
  • Use math when necessary, but keep it simple.
  • Link to basic terms if necessary.

Grammar and Mechanics

Adhere to specific rules of grammar and mechanics to help keep the writing clear and consistent. This section will lay out overall writing mechanics, which apply to all content unless otherwise noted in this guide.

Use

  • Oxford commas.
  • Pluralized, gender-neutral pronouns.
    • Use "they/their" instead of "he/she, his/hers."
    • Examples: "When they..." or "If users choose to X, then their..."
    • Or generalize the class of individuals. I.e. “When the Community”, “If users”
  • The % symbol. Do not spell out "percent."
    • Correct: 15%
    • Incorrect: 15 percent
  • Double quotes " " for phrases, quotes, etc.
    • Do not use single ' ' quotes.
  • Active, present voice whenever possible.
    • Correct: The contributor creates a forum post.
    • Incorrect: The forum post was created by the contributor.

Avoid

  • First-person language.
    • Examples: I, we, our, etc.
  • Second-person language (unless it is appropriate for a guide or action page).
    • Examples: "You then..." or "Now you should..."
  • Exclamation points.
  • Footnotes.
  • Parentheses for stating additional information.
    • Incorrect: Research Grants are larger-sized ($5,000 to $50,000) grants aimed at individuals or teams building projects.
    • Correct: Research Grants are generally larger-sized grants, ranging from $5,000 to $50,000, aimed at individuals or teams building projects.

Abbreviations

  • Use parentheses to define abbreviated terms the first time they appear in a given document.
    • Example: A Research Improvement Proposal (RIP) is a proposal framework to support new initiatives and to expand the scope of existing ones.
  • Do not provide an abbreviation for a term that is only used once.

Acronyms

  • Do not use apostrophes to pluralize acronyms. Instead, add an “s” at the end. To make an acronym plural:
    • Correct: RIPs
    • Incorrect: RIP's

Capitalization

  • Capitalize names, proper nouns, titles, cities, countries, nationalities, and languages.
  • Capitalize terms with definitions.
  • Use the Title Case Converter to keep titles consistent.
    • Follow The New York Times standard.
    • Capitalize the first and last words, all nouns, pronouns, verbs, adverbs, and adjectives.
    • Lowercase all articles, conjunctions, and prepositions.

Currencies

The examples below use dollars, but the same rules apply to all global currencies.

  • Use lowercase except when writing "US Dollar."
  • Use figures and the "$" sign in all except casual references or amounts without a figure.
    • Standard: "The book costs $4."
    • Casual: "Please give me a dollar."
  • For amounts under $1 million, follow this format:
    • Correct: $4, $25, $500, $1,000, $650,000.
  • For amounts over $1 million, use the word, not numerals.
    • Correct: "He is worth $4 million."
    • Incorrect: "He is worth $4,000,000."

Cryptocurrencies

  • When directly referring to the creation, destruction, or manipulation of a token (particularly as it relates to tooling):
    • Use the capitalized TLA version: DAI
    • Example: "Draw DAI against ETH from a Vault."
  • Similarly, when referring to exchange pairs:
    • Use: ETH/DAI
  • When referencing the token as a currency, in an instructional or conversational setting, or as a conceptual product of the Foundation or its systems:
    • Use: Dai
    • Example: "Dai is a price-stable asset that can be used as money."

Dates and Times

  • Generally, abbreviate the day of the week and month but write out the date. May spell out the day of the week and month for a more formal tone.
    • Correct: Wed, Oct. 20, 2021
    • Correct: Wednesday, October 20, 2021
    • Incorrect: 10/20/21
  • Use numerals and AM or PM, with a space in between. Don’t use minutes for on-the-hour time.
  • Always specify time zones. SCRF is international but our default time zone is ET. Abbreviate time zones within the continental United States as follows:
    • Eastern time: ET
    • Central time: CT
    • Mountain time: MT
    • Pacific time: PT
  • When referring to international time zones, spell them out: Nepal Standard Time, Australian Eastern Time. If a time zone does not have a set name, use its Coordinated Universal Time (UTC) offset.
    • Correct: 7:00 AM ET
    • Incorrect: 7am
  • Use a hyphen between times to indicate a time period.
    • Example: 7:00 AM - 10:00 PM ET

Decades

  • Do not use apostrophes to indicate decades. Instead, add an "s" at the end. To indicate a decade:
    • Correct: 1990s
    • Incorrect: 1990's

Lists

When bulleted and numbered lists contain complete sentences, capitalize the first word, and follow each with a period. If list items are phrases, no capitalization or punctuation is required.

  • Use parallel construction for each item in a list.
  • Start with the same part of speech for each item (in this case, a verb).
  • Use the same verb tense for each item.
  • Use the same voice for each item.
  • Use the same sentence type (statement, question, exclamation) for each item.
  • List items that include definitions should look like this:
    • Team: Core team and Advisers are critical to SCRF's success.
    • Community: Sentiment analysis is invaluable.
  • Use dashes rather than asterisks for unordered lists.
    • Correct: -
    • Incorrect: *
  • Alphabetize lists of names unless there is a clear priority at work.
  • Do not use ordered (numbered) lists unless order matters.
  • Ordered list items should use the #1 repeated.
    • Markdown will automatically generate numbers.

Example:

1. Item 1
1. Item 2
1. Item 3
   1. Item 3a
   1. Item 3b

Links

  • Use relative links when cross-referencing files from repositories on SCRF's GitHub.
  • Use absolute links and standard web URLs when referencing external resources.
  • Create descriptive hyperlinks and avoid generic language.
  • Include a . inside the link for sentences that end with a link.

Numbers

  • Spell out numbers below 10.
    • Examples: one, two, three, etc.
  • Use numerals for numbers above 10, unless starting a sentence.
  • For numbers with million, billion, or trillion, use figures in all except casual cases.
    • Standard: "The nation has 1 million citizens."
    • Casual: "I'd like to make a billion dollars."
  • Spell out fractions.
    • Correct: two-thirds
    • Incorrect: 2/3
  • Use decimal points when a number can’t be easily written out as a fraction, like 1.375 or 47.2.

Punctuation

  • Do not use exclamation points.
  • When writing a list, use the Oxford comma.
  • Use a colon, rather than an ellipsis, em dash, or comma, to offset a list.
    • Example: The writer posted on the forum.
  • Don't use ampersands (&) unless one is part of a company or brand name.
  • Use semicolons (;) sparingly. Try breaking up the sentence instead.
  • Use double quotes " " for phrases, quotes, etc. Periods and commas go within quotation marks. Question marks within quotes follow logic—if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.
    • Do not use single ' ' quotes.
  • Avoid dashes (—) and ellipses (...) unless needed.
  • Use a hyphen (-) without spaces on either side to link words into a single phrase.

Ranges and Spans

  • Spell out ranges or spans unless they relate to a certain time range.
    • Correct: It takes 10 to 30 minutes.
    • Correct: The class is from 10:00 AM - 11:00 AM ET.
    • Incorrect: It takes 10 - 20 minutes.

Submission Tips

Run all drafts through Grammarly regularly, and before final submissions.

  • Grammarly will catch most spelling and grammatical errors.
  • Copy rendered text into Grammarly and address any mistakes it flags.
    • HackMD does not identify spelling and grammatical errors.
    • Grammarly will miss errors if it's given raw Markdown text.
    • Be careful of copy and pasting code from Grammarly to VScode; Grammarly may mess with formatting.

When migrating to a new document

  • Leave a note in the old file.
  • Provide a link to the latest version.
  • Do not blindly accept Grammarly suggestions.
  • Review edits to make sure they make sense.

Naming Conventions

  • All titles of the docs should match the file names, which should match the named links in other docs.
  • Please do not use shorthand or new terms for existing documents.
  • All document names should use “snake case.”

Writing for Social Media

SCRF uses social media to engage with community members and the general public, and to share what SCRF or its members are up to. SCRF is careful to be deliberate in what the organization posts to social channels.

Overview

SCRF has a presence on a number of major social media platforms. Below are the most active accounts and what is posted on each:

Twitter: SCRF news and updates, research summaries, research pulse, events, media mentions, evergreen content, timely blockchain news, join us posts

LinkedIn: SCRF news and updates, recruiting content, media mentions, evergreen content

Guidelines

Writing for social media should generally follow the style points outlined in this Writing Style Guide. Some additional pointers include:

  • Write short, but smart
  • Twitter: 280 characters
  • LinkedIn: No limit, but aim for 1-2 short paragraphs
  • Use correct grammar and punctuation and avoid exclamation points.
  • Simplify ideas or reduce the amount of information being shared. Do not alter the spelling or punctuation of the words themselves. It is fine to use the shorter version of some words, like “info” for “information.” But do not use numbers and letters in place of words, like “4” instead of “for” or “u” instead of “you.”

Best Practices

  • Think of Tweets as micro pitches:
    • What is the hook?
    • What is the value?
    • How to find out more?
  • Threads are better than tweets
  • Use relevant targeted tags
  • Limit mentions
  • Message people for retweets offline, never in a post
  • For each post, add “For further info consider following @expert1 and @expert2” to the end
    • Correct: “In recognition of the great work by @ntnsndr, Professor of Media Studies at @cumediastudies and @MEDLabBoulder, SCRF will be supporting two of his governance research projects: CommunityRule and Exit to Community.”
    • Correct: “Notice to researchers: SCRF is looking for contributors to write summaries of academic papers focused on blockchain topics. Review our grants program to learn more.
    • Incorrect: “We are excited to share the work of @ntnsndr, Professor of Media Studies at @cumediastudies and @MEDLabBoulder!”
    • Incorrect: “Hey @ntnsndr, can you please retweet this post about you?”

Hashtags

SCRF employs hashtags deliberately to promote events or connect with specific community members. Do not use current events or trending hashtags to promote SCRF.

Trending topics

Do not use social media to comment on trending topics or current events that are unrelated to SCRF or to the blockchain. Be aware of any major breaking news when publishing social content.

Learn More About SCRF

SCRF is an interactive forum supported by an active international community. SCRF’s members work together to advance actionable blockchain research. Learn more about SCRF, and discover ways to get involved.