% Documentation guidelines

Documentation is not optional
=============================

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

[GNOME Documentation Style Guide](http://developer.gnome.org/gdp-style-guide/stable/gdp-style-guide.html)

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](http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines/TOC.cfm)

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](https://developer.gnome.org/gdp-style-guide/stable/gdp-style-guide.html#wordlist)
  - 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)
  1. Write the doc early (usability bugs)
  1. Brainstorm content (check with coders)
  1. Write, rewrite, and rewrite
  1. 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
==========

  - [GNOME Documentation Style Guide](http://developer.gnome.org/gdp-style-guide/stable/gdp-style-guide.html)
  - Microsoft Manual of Style
  - [Wikipedia Manual of Style](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style)
  - [Federal Plain Language Guidelines](http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines/TOC.cfm)
  - The Chicago Manual of Style
  - Wikipedia