-
Notifications
You must be signed in to change notification settings - Fork 1
Style Guide Draft
Introduction
Grammar & Punctuation
Voice and Tone
Bits & Pieces
Context
Word List
Future Directions
Further Reading
Credit
The necessity for creating a style guide stems from uPort's need to have a consistent writing identity. The current version of the technical writings and other written documents have vastly different use of language and style depending on the author, resulting in the lack of clarity and confusion. A guide, defining patterns that can be applied to different forms of documentation will improve clarity and cohesiveness.
The goal of this guide is to provide uPort with a writing identity for all external written communications. The tone and style of our writings should remain consistent within their context. By adhering to this guide, we will have the ability to represent uPort in a consistent way and ensure that while the authors of documents might differ, the same tone and voice is used regardless of who is writing it. Anyone joining an ongoing project can refer to this guide for the appropriate styles to use. And most importantly, it creates a future-friendly point of reference for our organization to modify and evolve over time.
There are inherent complexities to writing, including, but not limited to: punctuation, spelling, and grammar – some matters are subjective. For example, there are often different ways of spelling a key industry term (e.g. DApp, Dapp, dApp). While there might be multiple correct options for anything, consistency is crucial. Any content sent to uPort's editor will be assessed based on the assumptions of this document.
Aspects of this document will be updated on the first day of each month. This is done to consider the rapidly changing nature of the field, and to consider any feedback offered by our writers. It's my hope that this document will be used to achieve the greatest amount of clarity and strength in all external communications.
Good writing has an aliveness that keeps the reader reading from one paragraph to the next, and it's not a question of gimmicks to "personalize" the author. It's a question of using the English language in a way that will achieve the greatest clarity and strength. -William Zinsser
Proper grammar will give your writing a good structure, however, punctuation is the best tool you have for clarification. Incorrect punctuation can change the meaning of a sentence or cause the reader to lose track of what is being said. The following list is a short primer on basic rules for the use of punctuation. If you need further assistance, contact the editor or refer to the AP Style Guide.
Many of the functions historically served by colons are now done by the dash; nevertheless, colons still do a great job when an independent clause is followed by an idea directly related to it, such as a list. For example:
She told me her favorite car manufacturers are: BMW, Jaguar, and Lamborghini.
The following guidelines will help you correctly use a comma in most situations. Use a comma when:
- Joining two independent clauses and a coordinating conjunction (and, but, or, for, nor). For example:
Connecting to a VPN might be inconvenient, but it's necessary.
- After an introductory phrase, prepositional phrase, or dependent clause. For example:
To have an encrypted communication, you must connect to your VPN.
- Separating elements in a series, including the Oxford Comma. For example:
In my opinion, it's important to love, sleep, and read.
- Separating non-essential elements from a sentence. For example:
My shirt, the blue oxford, is being washed.
- Joining coordinate adjectives (adj that are equal and reversible)
- After transitional elements (however, for example, of course). For example:
Sara is a great student; however, she is also very playful.
Note: When joining two independent clauses, use a semicolon instead of a comma.
Follow these guidelines:
- Use it to amplify or justify a thought you stated in the first half of the sentence.
- Use it instead of parenthesis to set-apart a thought. For example:
He told me to go the store – I was supposed to make dinner – so I drove to town.
- Use it to denote an abrupt change in thought.
Hyphens are best used when trying to avoid ambiguity or forming a single idea from multiple words. Use an en dash:
- To link words into a single phrase (e.g. first-time)
- To indicate a range (e.g. Monday-Friday)
- To avoiding confusion when connecting two words (e.g. Small-business Owner)
They can be used interchangeably, but Italics are more modern. Italicize the word:
- When referring to the title of a book, film, works of art, journal, newspaper, magazine
- When you are referring to that word
- To add emphasis
- When using a foreign word
Parenthesis are usually used to set non-essential material apart from the sentence; however, it is also a clue that a sentence is becoming controlled. Try to avoid a parenthesis if you can, either by using two dashes or writing the sentence differently.
Don't expect a single sentence to do more work than it can. Use the period liberally, there is no minimum acceptable length for a sentence. If you must write a long sentence, make sure to keep it under control in syntax and in punctuation.
A semicolon is used to attach a related thought to the first half of a sentence; however, it brings readers to a stop, thus not as desirable in the fast-paced enviornment of the 21st century as it was in the 19th century. While semicolons can be used sparingly, it's better to use an em dash when appropriate. Use a semicolon:
- When joining two independent clauses
- When joining two clauses of equal importance
- To join two independent clauses when the second one starts with a conjunctive adverb (e.g. in fact, for example, for instance, in addition)
Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent. -George Orwell
This section lays out the necessary elements for writing empowering content through the intentional use of tone and voice. The most fundamental difference between the two is that while an author's tone might differ from one context to another, the voice remains consistent.
uPort's voice is human, friendly, informal, and straightforward. Use an active voice, unless it violets the orderly progression of a reader's attention from one entity to another. In your voice:
- Be confident, yet respectful
- Aim to empower the readers by educating them
- Write positively
- Be casual, but not sloppy
- Avoid jargons when you can
The overall tone of a piece of writing should be appropriate for the context in which it's written, and the target audience. In everyday life, you might use one tone when hanging out with friends, and another when at a meeting with a customer, the same principles apply here.
Adjust your tone depending on the emotional state the reader will likely be in. Are they trying to debug their code and likely annoyed? or have they just discovered uPort and think it's the coolest idea they've ever seen? When appropriate, such as in blogs and social media, don't be afraid to throw in a joke when you can.
Humor is best achieved by understatement, and there's nothing subtle about an exclamation point. -William Zinsser
In this section, I will cover some general tips that I couldn't fit elsewhere. Unless otherwise stated in the Context section, use these guidelines for your writing.
-
Use Georgia for the font-family.
-
Unless otherwise stated, write using the first-person point of view.
-
Use short words, avoid vague language, and be consistent.
-
Unless it's a well-known abbreviation (e.g. HTML), spell out the first time you use an abbreviation (e.g. PKI (Public Key Infrastructure)).
-
Dealing with gendered language:
- Avoid using gendered terms to the extent possible.
- Use alternatives, such as Company representative instead of Spokesman, but avoid using makeshift words. When in doubt check with Webster's New World Dictionary (5th edition).
- It's OK to use "they" as a singular pronoun, but plurals are less specific, so it'll weaken your writing.
- If you can address the reader directly as a way of avoiding the use of gendered language, do it, especially for instructional content (e.g. You'll often find …).
- If the strategies above don't work, consider converting the noun into a verb. Speaking for the company, Ms. Williams said…
-
Capitalization:
- The beginning of a sentence
- Proper nouns
- A person's title
- When dealing with article titles, capitalize: nouns, adjectives, verbs, adverbs, pronouns, and subordinating conjunctionhowever, do not capitalize: articles, coordinating conjunctions or short prepositions.
-
In Quotations:
- Capitalize the first letter
- Don't capitalize a fragment of a quote
-
Put emojis outside the end punctuation
-
Avoid double negatives
-
Avoid using synonyms for the same word in the same piece of writing
-
Place similar topics in the same paragraph
-
Links should provide information on the action or destination. Avoid saying "click here."
You must adjust the tone and layout of your writing, depending on the context in which you're writing in. While it's OK to use an emoji on social media, a developer who is reading through a guide might not be in the mood for one. Similarly, when replying to a question on Gitter, the response will likely be unstructured, whereas, our technical documents won't. This section will help clarify such matters.
Headings and subheadings should be brief and descriptive. They should be easily understood, but intelligent; conversational, but not stiff. The topic being discussed under each heading must remain relevant; if you find yourself veering off, it's time for a new subheading.
Use H1 for the main heading of the page, afterward, group content using subheadings. Use H2s to organize by a higher level of topics and H3 within each section to separate supporting information. The normal capitalization rules apply here.
Images are helpful tools for explaining a complex interaction. Use them when it can help with the comprehending a topic but avoid them when the same information can be communicated in writing.
To improve clarity, each image should try to accomplish one goal. For example, if a process looks different when performed on a phone vs a PC, provide readers with a separate image for each one.
At each step of the way provide a sample of the code for that step below the content. At the end of the section provide the entire sample in a single box.
Use a table when you're discussing several things within the same category, such as comparing data. When using a table make sure to:
- Use horizontal and vertical lines to separate rows and columns for better organization.
- Number the table and provide it with a short and descriptive title (e.g. Table 2. Deployed Markdown).
- Refer to the table in the text preceding it.
Use ordered lists only if you are providing step-by-step instructions. Separate the steps into logical chunks with no more than two related actions per step.
Use unordered lists to display examples. If there are more than 10 items on the list, use a table.
Write in an informal and friendly tone. Keep in mind that some of the people looking through the docs might be frustrated, adjust your tone accordingly. You should write using the second person point of view, so directly refer to the reader (e.g. Next, copy this line of code and paste it into your editor).
- Each section should start with a brief (1-3 paragraph) introduction, immediately following the main header.
- At the end of each section, provide a sample of the entire code.
- Make examples more relatable (e.g. "Alex" instead of "The recovering user").
- Put the most important information first.
- Place similar topics in the same paragraph.
The front matter is how the site generator is informed on handling each file. Each markdown document intended to be a source for the developer site must have a minimum set of front matter attributes, written in YAML.
When writing the front matter, place a modified version of what follows directly at the top of each markdown file with no preceding spaces.
title: "Attesting Credentials"
index: 1
category: "guides"
type: "content"
Title (Required)
The title is used for the page title as well as navigation links. Keep it short and identical to the H1 heading in most cases.
Category (Required)
Categories are used to aggregate markdown for header menus and contextual relevancy. The main categories are guides, overview, and reference, but new categories may emerge over time. When a new category that follows the proper conventions is added, it will be included in the header navigation menu.
Type (Required)
The type is important for publishing. If the type is not "content" it will not be published or displayed.
Index (Optional)
Think of this as the display order for the content; it is used to sort each category and control the ordering of the navigation links.
Note: if the frontmatter does not contain an index, the site-generator will assume it is a sub-content that does not belong in the table of contents or navigation menu.
Announcement (Optional)
This is used to broadcast a message across all pages on the site; use it sparingly.
Social media is for building relationships, educating, and sharing all the cool stuff we do. Keep your posts short, casual, and funny when appropriate.
There are many manifestations of social media. Our official social media channels are Twitter, Reddit, Gitter, LinkedIn, GitHub, Medium, and YouTube. This section will provide you with guidelines intended to help you appropriately connect with our followers.
- Build credibility: You can't expect to have an engaged audience unless you post regularly. There is a specific social media marketing document in the works.
- Add a bio: Write a bio that accurately describes who we are. Always include a contact method in case our customers or the media wants to reach out.
- Hashtags: Use them sparingly and intentionally. They are especially useful for promoting events and connecting with people at conferences.
- Schedule: Use salesforce to schedule posts at the most effective times. Turn off all scheduled posts when there is major breaking news.
- Character limit: Some platforms have character limits, others don't. If you're over the limit, either simplify your idea or reduce the amount of information you're sharing. Don't alter the spelling or punctuation of a word to meet character limits ("info" is fine, but "u" is not).
- Twitter: Product news, media mentions, brand marketing, events
- Reddit: Product news, media mentions
- LinkedIn: Career opportunities, conference photos, blog posts
- Gitter: Support, release news
- GitHub: Developer content, technical content
- Medium: Blogs, education
- YouTube: Marketing, education, conference talks
The words on this page often appear in our documents. While there is some level of subjectivity with a few of them, in favor of consistency, use the following when publishing content.
- dApp
- OK
- open-source
- uPort
- URL
- ERC-20, ERC-712
- e-commerce
- double-click
- emoji (singular, plural)
The following words must be separated by a dash if they are being used as a noun or adjective. There is no need for a dash if these words are being used as a verb.
- opt in (verb), opt-in (adjective, noun)
- pop up (verb), pop-up (adjective, noun)
- drop down (verb), drop-down (adjective, noun)
- back end (noun), back-end (adjective)
- front end (noun), front-end (adjective)
- login (noun, adjective), log in (verb) |
- Expand the Context section to include the following:Newsletters, Blogs, Release Notes, and Polls & Measures.
- Create a Design Guide
- Incorporate marketing strategies in our writings
- Webster's New World Dictionary, (5th edition)
- Associated Press Style Guide Handbook 2018
- On Writing Well - William Zinsser
- The Sense of Style - Steven Pinker
- Elements of Style - William Strunk Jr.
- Rules for Writers - Diana Hacker and Nancy Sommers
- Copy Hacker - Joanna Wiebe
Copy Hacker - Joanna Wiebe
On Writing Well - William Zinsser