% 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 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