% Documentation guidelines

Documentation is not optional

You won't do it "later"...

GNOME Documentation Style Guide

Style

  • Comprehensive: document extensively
  • Conformant: describe what you see
  • Clear
  • Consistent
  • Concise

Golden rules

  • Be concise:
    • 1 sentence < 25 words
    • 1 paragraph = 1 topic
    • 1 step = 1 action
  • Use a neutral tone
  • Write in plain English

Tone

Things to avoid:

  • Humor, personal opinions, colloquial language
  • Jargon, technical terms, topical expressions
  • Offensive language, avoid gender
  • Saying that things are easy or simple

Terminology

  • Consistency and simplicity
  • GNOME recommended terminology
  • Copy and paste!
  • Otherwise take early and collective decisions

Writing for the web

  • Structure visually
  • Use lists, bold, and notes
  • Short
  • Scannable

http://www.nngroup.com/articles/how-users-read-on-the-web/

http://www.nngroup.com/articles/be-succinct-writing-for-the-web/

International audience

Easy to read, easy to write :)

  • Use active voice, present tense, affirmative forms
  • Avoid contractions
    • isn't possible → is not possible → is impossible
  • Avoid noun strings
    • laboratory animal rights protection regulations → regulations to protect the rights of laboratory animals
  • Avoid possessive
    • file's properties → properties of the file

International audience

Think about translators

  • Avoid screenshots: mostly used to clarify context
  • Don't break translations
  • Less words, less work!

Process

  1. Get involved in the design (terminology, UI)
  2. Write the doc early (usability bugs)
  3. Brainstorm content (check with coders)
  4. Write, rewrite, and rewrite
  5. User review

Example 1

The Foobar applet is a handy little screen grabber.

Example 1

The Foobar applet is a handy little screen grabber.

You use the Foobar applet to take screenshots.

→ be neutral, be consistent

Example 2

In the menu tree you will notice that there are two main menu lists.

Example 2

In the menu tree you will notice that there are two main menu lists.

The menu tree contains two main menu lists.

→ use present tense, and active voice, avoid "there are"

Example 3

If you would like to place a menu item onto the panel, you can drag and drop from the menu to the panel and it will place a launcher there with all the appropriate properties set for you.

Example 3

If you would like to place a menu item onto the panel, you can drag and drop from the menu to the panel and it will place a launcher there with all the appropriate properties set for you.

You can drag a menu item from the menu to the panel. The drag action places a launcher on the panel with all the appropriate properties set.

→ split big sentences, be factual, keep it short

Ressources