TECH WRITER KODUJE PRESENTS
golden rules for writing docs
<Write in a simple way/>
- Use clear declarative sentences
- Use the active voice
- Be concise and get to the point quickly
- Avoid jargon, slang, and idioms
- Explain complex terms and acronyms
<Structure your writing/>
- Use headings and paragraphs
- Use tables to represent information more clearly, especially information that is repetitive or has a pattern
<Use lists/>
- Use ordered lists for procedures and or sets of items where numbers are useful
- Use bulleted lists for a sets of items where the order isn't important
- If you list three or more things, consider putting them in a bulleted list instead of listing them in a sentence.
<Create procedures for tasks/>
- Introduce the procedure with a short sentence explaining what the user will accomplish
- Break down the procedure into steps
- Don't use "then" and "next" - the sequence of steps is clear from step numbers
- Describe the result of the procedure
<Emphasize important info/>
- Use tips, notes, and warnings
<Be consistent/>
- Stick to one convention for presenting an element, e.g., use monospace for all commands.
- Always use the same word for a thing, using synonyms can cause confusion
<Make navigation easy/>
- Add a table of contents in long topics
- Use links
<Use graphics wisely/>
- Add graphics only where they add value
- Crop graphics to show only what's necessary
- Highlight important elements in the graphic
