InformationDesign

Differences between revisions 4 and 5
Revision 4 as of 2007-12-16 22:18:37
Size: 2830
Editor: cpc3-with4-0-0-cust1001
Comment: Added TOC
Revision 5 as of 2008-08-06 16:22:23
Size: 2831
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
||<tablestyle="float:right; font-size: 0.9em; background:#F1F1ED;margin: 0 0 1em 1em;" style="padding:2.0em;">[[Include(DocumentationTeam/StyleGuide/TableOfContents)]]|| ||<tablestyle="float:right; font-size: 0.9em; background:#F1F1ED;margin: 0 0 1em 1em;" style="padding:2.0em;"><<Include(DocumentationTeam/StyleGuide/TableOfContents)>>||
Line 5: Line 5:
[[TableOfContents(2)]] <<TableOfContents(2)>>
Line 31: Line 31:
The section [:../InternationalAudience:Writing for an International Audience] gives more guidance on writing style. The section [[../InternationalAudience|Writing for an International Audience]] gives more guidance on writing style.

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 if documentation is clear, concise, and consistent. As well, 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 users need to understand a procedure. Format explanatory text in paragraphs.

Procedural writing is used for telling readers precisely what steps they must take to complete a task. Write procedural text as numbered lists. Tell users what to expect when they've finished.

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 users see the overall content of the page by scanning it.

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

Lists allow users 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 people pick words out of paragraphs, lists and examples; giving them an idea of the topic details before reading.

Formatting Conventions lists visual styles and their use.


CategoryDocteam

DocumentationTeam/StyleGuide/InformationDesign (last edited 2010-03-23 09:55:07 by c220-237-150-52)