Technical Writing Style Guide

Independent Tech Writers Co. strives for a consistent and high quality style of technical writing throughout its entire body of work. Here are the formal standards and best practices for all pull requests initiated by the technical writers working with ITW Co.

Table of Contents

1. General Writing
2. Additional Standards
3. Code & Comments
4. Commit Messages
5. Writing for User Interfaces

General Writing

When editing README files and other long-form documentation, be sure to follow all commonly accepted rules of grammar, punctuation and spelling. Spellcheck everything. Try to be concise without being terse: A README file provides the voice & tone for the entire codebase and should work to ensure the code is the center of attention, not the documentation.

Use the Economist Style Guide as a general guideline for writing in English. Although its intended audience is the journalism community, it also provides a useful starting point for technical writing.

Here are some important points to follow from the Economist guide.

• 1.1 Dates: Dates are month, day, year — no dashes. For date ranges, use a single hyphen with no spaces.

  Good:

   July 20th 2003. Monday July 9th. July 4th-8th 1776.
  

  Bad:

   July 20, 2003. Monday, July 9. July 4th - 8th.
  

• 1.2 Numerals: Try to spell all numbers zero through nine — unless it looks strange — but always use numerals at 10 and above (until you reach thousands, millions, billions, etc).

  Good:

   Take five minutes. Hold the third note. One in a million.
  

  Bad:

   Take 5 minutes. Hold the 3rd note. 1 in a million.
  

• 1.3 Periods within parentheses: Don't use periods within parentheses or brackets unless they include one or more full sentences.

  Good:

   This should feel natural (like a logical next step).
   Perfect! (That was indeed our intent.)
  

  Bad:

   This should feel natural (like a logical next step.)
   Perfect! (That was our intent).
  

• 1.4 No periods in abbreviations or titles

  Good:

   The USA
   JP Morgan
   Mr and Mrs Smith
  

  Bad:

   The U.S.A.
   J.P. Morgan
   Mr. and Mrs. Smith
  

• 1.5 Sorry, no Oxford comma: Although contentious, we recommend the Economist method: no Oxford comma unless the sentence would become unclear otherwise.

  Good:

   Please update your repository, packages and modules.
  

  Not-so-good:

   Please update your repository, packages, and modules.
  

⬆ back to top

Additional Standards

The Economist guide wasn't written with Markdown in mind, so here are some additional rules to follow when editing documentation:

• 2.1 Use Markdown whenever you can: Markdown is well-supported and degrades fairly well. When editing a README file, or any in-codebase documentation, use Markdown unless the project requires otherwise.

  Use the GitHub Markdown standard — it's easy to learn, flexible and mature. Use a Markdown editor — like the built-in Markdown previewer for Atom, or MacDown (for Mac) — to ensure your Markdown code looks as desired before committing it.

• 2.2 List items: Use Markdown list items liberally. And be sure to use a period only if the list item contains two or more full sentences. Otherwise, no period.

  Good:

   - Update README file
   - Fix any parsing bugs
   - Rename the repository. The joke's not funny anymore.
  

  Bad:

   - Update README file.
   - Fix any parsing bugs.
   - Rename the repository. The joke's not funny anymore
  

• 2.3 Use periods for ellipses: When writing an ellipsis, don't use the actual ellipsis character (…, which is option+; on a Mac keyboard, and the … HTML entity), even though it is technically the proper one to use. Just use three consecutive periods (...) since most future editors will write it that way.

• 2.4 Don't use curly-quotes for apostophes or quotation marks: Use prime marks (' and ") instead of proper quotation marks (‘’ and “”). The "proper" way to write an apostophe is technically with the curly quotation mark (’, which is the HTML symbol ’). However, it's much more common in daily communication to use the prime mark ('), which is what is on a standard English-language keyboard. So, when contributing to a shared project, just use the prime mark to ensure future editors don't introduce inconsistencies. This also goes for double-quotes (use "" instead of “”).

  Good:

   - There aren't any other options!
   - We are not a "traditional startup".
  

  Bad:

   - There aren’t any other options!
   - We are not a “traditional startup”.
  

⬆ back to top

Code & Comments

Contributing code should always be done in accordance with the contribution guidelines and standards already in place for the project you're contributing to. Defer to the project precedents for everything from tabs-vs-spaces to naming conventions. When in doubt, use well-respected style guides for the particular programming language (like the AirBnB JavaScript Style Guide for JavaScript and JS-like languages, for example).

Code commenting, however, can be fairly standard. Follow these rules.

• 3.1 Capitalize consistently: Capitalize traditionally, with the first letter of a comment always being capitalized (unless it's a special variable or keyword, of course).

   // This is a good comment
  
   // So is this one
  
   // this isn't a good comment, however
  

• 3.2 Do not end single-sentence comments with periods: If a comment is only one sentence, do not include a period at the end of it. If a comment has two or more sentences, use periods. This is identical to the rule regarding list items above.

   // Good: A good one-sentence comment has no ending period
  
   // Also good: Periods are required here. This comment has two sentences.
  
   // Bad: A one-sentence comment with a period.
  

• 3.3 Empty lines: A comment line descibing the next line of code should have an empty line above it, and no empty line below it.

  Good:

   var text = someLineOfCode();
  
   // Ensure the text is formatted properly
   text = text.formatProperly();
  

  Bad:

   var text = someLineOfCode();
   // Ensure the text is formatted properly
   text = text.formatProperly();
  

  Also bad:

   var text = someLineOfCode();
  
   // Ensure the text is formatted properly
  
   text = text.formatProperly();
  

• 3.4 Avoid sequential phrasing: Code comments shouldn't be "stateful"; that is, they shouldn't rely on comment Y always following comment X. To that end, avoid using sequential phrasing, like "first", "then" or "after that".

  Good:

   // Assign the function output to a variable
   var text = someLineOfCode();
  
   // Ensure the text is formatted properly
   text = text.formatProperly();
  
   // Return the text
   return text;
  

  Bad:

   // First, assign the function output to a variable
   var text = someLineOfCode();
  
   // After that, ensure the text is formatted properly
   text = text.formatProperly();
  
   // Finally, return the text
   return text;
  

• 3.5 Use prime marks for apostophes: As mentioned in #2.4, do not use curly-quotes (‘’ or “”) for apostrophes or quotation marks. Use prime marks (' and ") instead.

• 3.6 Avoid commenting at the end of a line of code: Ideally, comments belong on a line of their own. Only put them at the end of a line of code if you must (like in the rare situation that you must comment on just one item in a large array). Always try to avoid this if possible, however.

  Good:

   // Truncate the string at 35 characters
   $string.truncate(35);
  

  Bad:

   $string.truncate(35); // Truncate the string at 35 characters
  

  Possible exception to this rule:

   var myArray = {
   	'orgeat',
   	'passionfruit',
   	'honeySyrup',    // This must be camel-cased!
   	'falernum',
   	'gin',
   	'rum',
   	'lime'
   }
  

• 3.7 Be thoughtful with line length: When a comment line length is going to exceed the column width specified for a project, break the comment into multiple lines. How you do this will depend on the programming language. If the project hasn't specified a column width, break at about 100 characters.

  Good:

   /**
   * I'd just like to interject for a moment. What you're referring
   * to as Linux, is in fact, GNU/Linux, or as I've recently taken
   * to calling it, GNU plus Linux.
   **/
  

  Bad:

   // I'd just like to interject for a moment. What you're referring to as Linux, is in fact, GNU/Linux, or as I've recently taken to calling it, GNU plus Linux.
  

⬆ back to top

Commit Messages

Commit messages are generally only meant to be read by developers and those with technical knowledge of a project. This means writing style is more flexible here, since it won't reflect on the voice & tone of the project as a whole.

Always be sure to follow any commit formatting rules enforced by the project. Some projects, like the Linux kernel, will reject any pull request out-of-hand for even a small deviation from the commit template. Never compromise your work by neglecting to follow a direction.

For projects without strict commit standards: Try your best to describe your commit entirely within the commit message summary. This is a maximum of 50 characters, so there's no room for extended descriptions. If you absolutely must give more information, give a descriptive summary of less than 50 characters, then be as straightfoward as possible in the extended description. Follow the code-commenting rules as described above.

• 4.1 Always use the second-person voice when writing a commit summary: Write your summary in the present-tense, as if it were a verbal command you could apply to the codebase.

  Good:

   $ git commit -am "Update the README with examples"
  

  Bad:

   $ git commit -am "Updated the README with examples"
  

  Bad:

   $ git commit -am "Updating the README with examples"
  

• 4.2 Capitalize your commits: Capitalize each sentence in your commit summary (although in truth you should rarely have more than one sentence).

• 4.3 Don't use periods for single-sentence commits: Follow the same rules as code commenting above. If your summary is just one sentence, don't put a period at the end of it. If it's more than one sentence (although, again, this is very rare) use periods at the end of each sentence.

⬆ back to top

Writing for User Interfaces

Writing for users is best left to the project maintainers and their copywriting team, since it needs to reflect the precise voice & tone the software and brand aims to create. However, if asked to edit messaging for user interfaces, use Google's style guide for UI writing as your guide. It's an indispensable tool for messaging within an interface.

Note that this means some rules in this guide, like the ones regarding apostrophes, must be superseded. Here are just a few of the important points to note from Google's guide.

• 5.1 Be friendly, respectful, and focus on the user: Your app's text should complement its design: intuitive, efficient, casual, and trustworthy.

  Good:

   MyApp isn’t responding
   -- Do you want to close it?
  

  Bad:

   Sorry!
   -- Activity in MyAppActivity (in the MyApp app) is not responding
  

• 5.2 Be positive: Present information in a positive light. It's reassuring.

  Good:

   Use 24 characters or fewer for file names
  

  Bad:

   Your file name must be less than 25 characters
  

• 5.3 Be essential: Communicate essential details, so that users can focus on their own tasks. Sometimes the most effective UI contains no text at all.

  Good:

   Your phone is contacting Google. This can take up to five minutes.
  

  Bad:

   Your phone needs to communicate with Google servers to sign in to your account. This may take up to five minutes.
  

⬆ back to top

Contributing

Please feel free to contribute to this guide. Pull requests that follow the rules outlined in this document are happily accepted.