Writing Guidelines

Acronyms

Spell out acronyms at least once, early in the document, then use the acronym alone.

Capitalization

Capitalize in the following situations:

• Initial letter of the first word in a list
• Initial letter of a sentence
• All words in page titles and subheadings (e.g., Approving Images In The Moderation Queue)
• When referencing an interface component (e.g., Page Configuration settings)
• All letters in acronyms, unless the acronym is a well-known exception

Tone

Use a neutral tone, free of personal opinion or personal flavor. Humorous or inappropriate tone distracts from the information you are trying to provide. Also, using a neutral tone makes it easier to maintain consistency across a documentation set when there are multiple writing contributors.

Numbers

Use figures for 10 and above; spell out numbers for nine and below, even when numbers are mixed in the same sentence (e.g., Overall, six out of 27 residents agreed.).

Pronouns

Use gender neutral pronouns or rewrite your sentence so no pronoun is needed.

Section Headings

Use the following guidelines to write section headings:

• Use H2, H3, and H4 headings to chunk information into easy-to-identify sections. Use specific titles that summarize the information in the associated sections.
• Keep headings short.
• Use parallel construction in headings of the same level.
• Do not use more than four heading levels.
• Limit the use of H4 headings.
• Try to have at least two headings within a section.
• Avoid starting a heading with an article. (e.g., The Media Library vs. Media Library)

Lists

• Put series of related points in a bulleted list.
• Put series of actions in a numbered list.
• Use parallel structure: Every bullet should start with the same part of speech (e.g., all verbs or all nouns).
• Every bullet should be a sentence fragment or every bullet should be a complete sentence — do not mix and match.

Tables

Use tables when a 2 or 3-column format would be easier to read than paragraph format.

 

Emphasis Techniques

We are using two different types of notices: anecdotal notes and important warnings. Both notice types are used in the same general scenarios, but important warnings should be used sparingly and reserved for use when the implications of not heeding the warning are significant.

Anecdotal Notes

To emphasize points, remind readers of something, indicate minor potential problems in the outcome of what they are doing or make recommendations

Formatting & special considerations:

Use “Note Message” format in the Formats dropdown of the Visual Editor.

Example:

Important Messages & Warnings

Use this type of notice:

• when a process or concept has a dependency on some other action. Example: If a plugin needs to be activated or configured prior to using a feature ( CNN Van Video)
• when there is a risk associated with a process. Examples:
  • security risk (sharing SSH passphrases and private keys with third parties)
  • risk of breaking site display (adding items to main menu might break the header)
• if there are other processes that impact the result of this concept or process. For example, lists have configuration settings in the list template, in the list itself, and on the page.  Documentation about the each aspect of

Formatting & special considerations:

Use “Important Message” format in the Formats dropdown of the Visual Editor.

Example:

Bold Text Rules

Do bold:

• Buttons and interface elements that initiate a command
  Examples:
  • Click View Trash in the upper right corner.
  • Click the Add Media button to open the Media Library
• Table or figure titles
• Column headings in tables

Do not bold:

WordPress interface field labels and box labels

 

Cross-linking and Referencing Other Documentation

 

Frequently Asked Questions

Frequently asked questions are often included at the bottom of a document as a place to address troubleshooting issues or common points of confusion. Make each question an h3 and apply the FAQ format from the format dropdown in the visual editor.

Example:

How did you create such amazing knowledge base documentation?