Ubuntu Wiki

Define Your Audience

TODO: Importance of knowing who you are writing for.

Write to Facilitate Scanning

Users need to find information quickly. People don't read documentation as much as they scan it for solutions to their immediate problem. Writing and presentation styles that seem redundant in essays or other texts are often helpful to people scanning for information.

Readers can find and absorb information more quickly when documentation is clear, concise, and consistent. Also, translators can more easily translate documents with these attributes.

• Writing must be clear: Write short, active sentences using everyday vocabulary. Maintain a visual separation between page elements.

• Writing must be concise: Minimize content so it can be found and remembered. Keep pages short, modular, and focused on a single topic.

• Writing must be consistent: Refer to one thing or idea with the same word throughout the page. Use headlines, lists, and emphasis to signal importance.

Match Writing Style to Purpose

Use a writing style that fits the text's purpose. The most useful styles in documentation are explanatory, procedural, and descriptive.

Explanatory writing is used for special language or concepts that readers need to understand a procedure. Format explanatory text in paragraphs.

Procedural writing is used to explain to readers precisely what steps they must take to complete a task. Write procedural text as numbered lists. Inform readers what to expect when they have finished the task.

Unlike the other two, descriptive writing is used primarily in reference material. It gives a short definition or identifies where a feature can be found. Lists and tables are useful in formatting descriptive text.

The section Writing for an International Audience gives more guidance on writing style.

Match Formatting to Importance

Formatting text gives a visual hierarchy that lets readers see the overall content of the page by scanning it.

Headlines summarize the topic of the underlying information. Scanning headlines gives readers an accurate picture of the detailed contents.

Lists allow readers to skip over explanations they don't need and get straight to a solution.

Admonitions (callouts) package relevant information that doesn't fit into the primary flow of the topic.

Emphasis lets readers pick words out of paragraphs, lists, and examples. Emphasizing key concepts provides readers with an overview of the topic before reading the relevant text.

Formatting conventions list visual styles and their use.

CategoryDocteam