Learn how to write technical documentation.
The documentation system: learn how to write tutorials, how-to guides, reference guides, explanation.
Training of 2-3 hours: Google Technical Writing Courses for Engineers.
- Setup a spell checker in your IDE, even better a "writing assistant" (popular ones LanguageTool, Grammarly).
- Determine what your audience needs to learn, fit documentation to your audience.
- Write in the second person. Refer to your audience as “you” rather than “we”.
- Create great opening sentences that establish a paragraph's central point.
- Prefer active voice to passive voice:
The mat was sat on by the cat.->
The cat sat on the mat.
- Prefer task-based headings.
- Prefer list to long sentences. Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant.
- Explain and give information progressively.
- Usage sections should feel like tutorials that call the user to action - e.g. "create a mapping".
- In tutorials, reinforce concepts with examples, note problems that readers may encounter.
- Read documents out loud (to yourself).
- Ask for review.
- When using MkDocs, run the live server and verify that the page renders correctly (e.g. code snippets).