The writer's job is to make the reader's job easier.

Background

This entry describes style guidelines for writing DART documentation. The guidelines are taken from the Google developer documentation style guide and the book Writing Science by Joshua Schimel.

Recommendations

Tone and Voice

Aim for a voice that is friendly and instructive. Imagine yourself as a knowledgeable friend who is attempting to teach someone how to perform a task that is within their ability but that is somewhat difficult. Provide all of the necessary details needed to complete the task and omit unnecessary details. Use active voice. The subject of the sentence should be the actor that performs the action. When using passive voice, the actor is sometimes omitted from the sentence, which makes it more difficult to interpret.

Point of view

Write in second person. Address the user as "you" and refer to the writer as "DAReS staff." Maintaining this consistency avoids the use of ambiguous pronouns such as "we" and "us." Non-native English speakers can be unfamiliar with the construct that "we" can refer to the reader and writer or "we" can refer exclusively to the writers. 

Not recommended:

Users who desire to run DART with this model should contact us by emailing dart@ucar.edu.

Recommended:

If you want to run DART with this model, contact DAReS staff by emailing dart@ucar.edu.

Tense

In general, write in present tense.

Audience

Write for a global audience. Many DART users do not speak english as their first language. Avoid colloquialisms or ambiguous terms. Google provides a word list that outlines issues that can cause confusion or consternation among users.

Not recommended:

If you wish to get a copy of this data and do not have access to GLADE, contact DAReS staff by emailing dart@ucar.edu.

Recommended:

If you want a copy of this data and don't have access to GLADE, contact DAReS staff by emailing dart@ucar.edu.

Language

Use inclusive language.

Sentences

Always write in complete sentences. While it may be faster for a native English speaker to skim over sentence fragments that omit objects or subjects, it is very difficult for non-native English speakers to interpret sentence fragments. Furthermore, if a user attempts to use an automated translator such as Google translate, the translated output will be easier to comprehend if the input consists of complete sentences.

Sentence structure

In technical writing, the opening and resolution positions in a sentence are known as the "topic" and the "stress." When introducing a new term it is helpful to use concepts that should already be familiar to the user in the topic at the beginning of the sentence and then define the unfamiliar term in the stress at the end of the sentence.

Not recommended:

The Globally Accessible Data Environment (GLADE) is the filesystem attached to NCAR's supercomputer.

Recommended:

The filesystem attached to NCAR's supercomputer is known as the Globally Accessible Data Environment (GLADE).

Several sentences can be strung together using this pattern to introduce multiple concepts.

Recommended:

The filesystem attached to NCAR's supercomputer is known as the Globally Accessible Data Environment (GLADE). All filepaths on GLADE have the structure: /glade/*.

Contractions

Use negation contractions such as isn't and don't instead of is not and do not. It is more likely that a reader will accidentally skip over reading the word not than they will skip over the contraction n't.

Ellipses

According to the Google entry, "When ellipses are used to indicate hesitation, they are called suspension points. Don't use ellipses this way."

Capitalization

Use sentence case for all section headings, titles and navigation items. This makes it easier to link to other sections within the body of the text. Follow the capitalization rules for American English.

Exclamation points

Avoid using exclamation points except when they are contained in code examples. Use a notice such as "Caution" or "Note" to add emphasis to a point.

Compound words, or not,

from https://developers.google.com/style/word-list, which contains a broader style guide than this list.
If you have to guess, the noun form is usually a compound word,
while the verb is 2 words (usually a verb and a preposition), and the adjective is hypenated.

Next section