Documentation Style Guide

Spelling and grammar

American spelling and grammar

Whenever U.S. English and British (or other) English spelling or usage disagree, standard U.S. spelling and usage is preferred.


The colour of the button is grey.


The color of the button is gray.

Quote marks

  • Quote marks should generally be avoided if possible.

  • Smart quotes (also known as curly quotes or directional quotes) are not permitted in source files.

Avoid quote marks

Quote marks are used in prose writing to indicate verbatim text. This is rarely useful in technical writing, as verbatim text usually requires a more specific semantic markup.


Click the button that says, "Save."


Click :guilabel:`Save`.


You may see an error message that says, "Something went wrong."


You may get an error: ``Something went wrong.``

Straight quotes

Any time that you do need to use quotation marks, use straight (or plain) quotes. Sphinx and Docutils will output the typographically correct quote style.

Click instructions

When giving user interface click instructions always use Click rather than Click on.


Click on :guilabel:`Create user`.


Click :guilabel:`Create user`.

Serial comma

In a comma-delineated list of items, the penultimate item should be followed by a comma.


Apples, oranges and pears.


Apples, oranges, and pears.

A bulleted list is often more clear than an inline list.


You will need to be familiar with git, GitHub, and Python.

Possibly Better

You will need to be familiar with:

- git
- GitHub
- Python

There’s no hard rule about which to use in any situation. Use your judgement: try it both ways and see which is more clear.

Ordered and unordered lists

An order list is numbered. It should be used when the order of the list is essential. For example, when enumerating a series of steps in a procedure.


- First we do this.
- And then we do this.
- And the we do this.


1. Do this.
2. Do this.
3. Do this.

An unordered list is bulleted. It should be used for a collection of items in which order is not essential.


1. apples
2. oranges
3. bananas


- apples
- oranges
- bananas

Avoid Latin

Several Latin abbreviations are common in written English:

At best, these present a minor barrier to understanding. This is often made worse by unintentional misuse.

Avoid Latin abbreviations.


If you are writing about a specific process (e.g., installing an application)...


If you are writing about a specific process (for example, installing an application)...


Et cetera (or etc.) deserves a special mention.

Et cetera means “and all the rest,” and is often used to indicate that there is more that could or should be said, but which is being omitted.

Writers often use etc. to gloss over details of the subject which they are not fully aware of. If you find yourself tempted use etc., ask yourself if you really understand the thing you are writing about.

Avoid unneeded words


Adverbs often contribute nothing. Common offenders include:

  • simply

  • easily

  • just

  • very

  • really

  • basically


To open the file, simply click the button.


To open the file, click the button.


You can easily edit the form by...


To edit the form...

Filler words and phrases

Many words and phrases provide no direct meaning. They are often inserted to make a sentence seem more formal, or to simulate a perceived style of business communication. These should be removed.

Common filler phrases and words include:

  • to the extent that

  • for all intents and purposes

  • when all is said and done

  • from the perspective of

  • point in time

This list is not exhaustive. These “canned phrases” are pervasive in technical writing. Remove them whenever they occur.


Semicolons are used to separate two independent clauses which could stand as individual sentences but which the writer feels would benefit by close proximity.

Semicolons can almost always be replaced with periods (full stops). This rarely diminishes correctness and often improves readability.


These "canned phrases" are pervasive in technical writing; remove them whenever they occur.


These "canned phrases" are pervasive in technical writing. Remove them whenever they occur.


Third-person personal pronouns

Third-person personal pronouns are:

  • he/him/his

  • she/her/her(s)

  • they/them/their(s)


While some people consider they/them/their to be non-standard (or “incorrect”) as third-person singular, it has gained wide use as a gender-neutral or gender-ambiguous alternative to he or she.

There are two issues with personal pronouns:

  • gender bias

  • clarity

To avoid gender bias, the third person gender-neutral they/then/their(s) is preferred over he or she pronouns when writing about abstract individuals.


The enumerator uses his device.


The enumerator uses their device.

Unfortunately, they/them/their is not a perfect solution. Since it is conventionally used as a plural pronoun, it can cause confusion.

Therefore, avoid the use of personal pronouns whenever possible. They are often out of place in technical writing anyway. Rewriting passages to avoid personal pronouns often makes the writing more clear.


When using Collect, first the enumerator opens the app on their device. Then they complete the survey.


To use Collect:

- open the app
- complete the survey


Same, when used as an impersonal pronoun, is non-standard in Modern American English. It should be avoided.


NEMO is a data collection tool. The same can be used for...


NEMO is a data collection tool. It can be used for...


NEMO is a data collection tool that is used to...


Title case and sentence case

Document titles should be in Title Case – that is, all meaningful words are to be capitalized.

Section titles should use Sentence case – that is, only the first word should be capitalized, along with any proper nouns or other words usually capitalized in a sentence.

Verb forms

If a document or section describes a procedure that someone might do, use a verb ending in -ing. (That is, a gerund.) Do not use the “How to…” construction.


How to install NEMO


Installing NEMO

If section title is a directive to do something (for example, as a step in a procedure), use an imperative.

Installing NEMO

Download NEMO

Section content here.

Section labels

Section titles should almost always be preceded by labels.

The only exception is very short subsections that repeat — like the Right and Wrong titles in this document.

In these cases, you may want to use the rubric directive.

Other titling considerations

  • Do not put step numbers in section titles.

  • Readers skim. Section titles should be clear and provide information.


This document is a derivative of the original ODK style guide licensed under a Creative Commons Attribution 4.0 International License.