We want our documentation to be easy to read and understand. This document describes guidelines for writing documentation that is clear, concise, confident, and courteous.
Refer to Structure and formatting for details on organizing content and how we use reStructuredText and Sphinx.
Write using simple English: Be brief and communicate only the information that is needed. Be friendly and informative. Emphasize clarity and avoid unnecessary complicated or technical terms. Make the content accessible to non-native speakers.
Use short sentences and paragraphs. Stick to the principle of one main idea per sentence, plus one additional point if needed. Each paragraph should address one main idea. Remember the basic structure of a paragraph: Introduction, body, and conclusion.
We write for our peers and want to be familiar. Take a personal tone as if you were speaking directly to the reader. Use “you” to address the reader and “we” to refer to our view. Be professional, respectful, and cooperative.
Assume your audience has the same level of technical understanding and expertise as you did when you first started collaborating. Do not talk down to our readers, but also do not assume they know everything about the subject. Offer brief explanations or summaries of common knowledge if a significant portion of readers might benefit.
Use simple words¶
Use simple words to increase reader comprehension and reduce ambiguity. Follow our tips for making good word choices:
Avoid jargon: Write for your audience, using everyday language where possible, and technical terms where appropriate. Avoid clichés, idioms, and metaphors.
Be consistent: Use one term for each concept or action and use it consistently.
Avoid “fancy” words and phrases: If there is a simpler word or phrase, use it.
Use this Not this start, begin commence so consequently more than in excess of if in the event of before prior to if you want should one wish use utilize example instance
Avoid overuse of product name¶
Use product names only when necessary. Typically, you can rewrite sentences to remove the product name with no change in meaning, which keeps the content concise and scannable.
Avoid using the product name in page titles and headings.
Organize your content to make it scannable for the reader, which helps them find what they need quickly, and to understand the information more efficiently.
- Put the most important content first. Make sure your introduction clearly communicates what the reader can find on the page. Present the point of the document first, and organize supporting information towards the end of the page.
- Write scannable headings. Expect readers of documentation to skim and scan the content, and to leave if they don’t find what they need quickly. Good headings add organization to your content and help the reader to find and understand content more effectively. Follow our guidelines for writing effective Headings.
- Write great link text. Great link text tells the reader what they can expect when they click on a link. It also helps make the page more scannable. Follow our guidelines for writing Link text.
Use these guidelines to write effective headings:
- Be concise and descriptive. Use only the words necessary to describe the section.
- Use sentence case. Capitalize only the first word and proper nouns in a heading.
- Avoid punctuation. Unless your heading is a question, don’t use sentence punctuation in headings.
- Use parallel structure. Headings at the same level should use the same grammatical pattern. This provides structure to the document and helps users find information more easily. See Parallelism.
- Use strong verbs. Strong, active verbs get to the point. Avoid -ing verbs, such as Running, Testing, etc.
For example, two headings at the same level:
Install software Configure software
Installing the Software on the Platform Software Configuration.
Passive verbs make writing stuffy and formal. Use strong verbs to get to the point and avoid unnecessary words and phrases.
Commands, also called imperatives, are the fastest and most direct way of giving someone instructions. For example:
Send it to me.
I would appreciate it if you would send it to me.
Use present tense¶
Use simple present tense instead of future tense for most text. Search for the words “will” or “shall” to find future tense instances. Future tense is acceptable for conditional statements, such as in a caution or a warning. For example:
The system operates at a nominal temperature of 180 degrees Fahrenheit.
The system will operate at a nominal temperature of 180 degrees Fahrenheit.
Avoid nominalizations, which are nouns formed from verbs.
We discussed the matter.
We had a discussion about the matter.
IT has installed the software.
IT has completed the installation of the software.
Avoid words ending in -ing¶
Avoid using words ending in -ing unless they are part of a technical name. For example:
There is no way to verify this.
There is no way of verifying this.
Use the active voice¶
Use active voice whenever possible to show who or what is performing an action.
- Active voice follows standard English word order: SUBJECT–VERB–OBJECT (where the OBJECT is optional).
- Passive voice reverses the order and weakens the verb: OBJECT–be VERB–by SUBJECT (where the OBJECT is optional).
I made a mistake.
A mistake was made. *(By whom?)*
We released version 2.0 in June.
Version 2.0 was released in June.
Noun phrases (a noun and other words that describe or modify it) can be difficult to understand. Try to limit the number of modifiers in a noun phrase to two. For example:
Integration policies for power management mechanisms.
Power management mechanism integration policies.
Parallelism refers to the practice of using similar patterns of grammar, and sometimes length, to coordinate words, phrases, and clauses.
Use parallel construction in lists. The table below shows some unparallel structures and how they can be made parallel with a little rewording.
|Parallel (do)||Unparallel (don’t)|
|I like practicing my accordion, reading sci-fi, and eating peanut butter and pickle sandwiches.||I like practicing my accordion, reading sci-fi, and to eat peanut butter and pickle sandwiches.|
|For breakfast he likes coffee and bacon.||For breakfast he likes coffee and to fry bacon.|
|Apples or bananas are a good snack.||Apples or a banana are a good snack.|
This section covers common grammatical topics relevant to our documentation. For detailed explanations of correct grammar and punctuation, use one of our preferred references.
The capitalization style for all documentation is sentence case. Words should only be capitalized when they are proper nouns or refer to trademarked product names.
Do not capitalize a word to indicate it is more important than other words. Never change the case of variable, function or file names - always keep the original case.
Software version capitalization¶
When listing software or hardware version numbers, the word “version” or letter “v” are lowercase. The v is closed with the number (no period).
- Widget Pro version 5.0
- Widget Master v2.1.12
Avoid using contractions, such as it’s, they’re, and you’re, because they may be unclear to non-native English-speaking audiences.
Follow these guidelines for quotation marks:
- Restrict use of quotation marks to terms as terms.
- Do not use quotation marks for emphasis; use italics for emphasis.
- Avoid using single-quote marks.
Commas and colons¶
This section addresses common use of commas, semicolons, and colons in our documentation. Refer to one of our preferred references for further details.
Use the serial comma¶
When writing a series of items, use the serial comma before the final and and or to avoid confusion and ambiguity. For example:
Mom, Dad, and I are going to the game.
Mom, Dad and I are going to the game.