- contribute
- how
- promote
- material
- slides
- Paris-Tails HackFest-201407
- Documentation
- documentation
% 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
- Get involved in the design (terminology, UI)
- Write the doc early (usability bugs)
- Brainstorm content (check with coders)
- Write, rewrite, and rewrite
- 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
- Microsoft Manual of Style
- Wikipedia Manual of Style
- Federal Plain Language Guidelines
- The Chicago Manual of Style
- Wikipedia