Technical Writing Best Practices for Engineers

Google's Technical Writing One and Technical Writing Two are free, short and written for engineers. Technical Writing One covers words, active voice, short sentences, lists, paragraphs, audience and documents; Technical Writing Two covers self-editing, organising large documents, illustrating, sample code and using LLMs in technical writing.

Diátaxis is a framework for organising documentation around four user needs: tutorials (learning), how-to guides (achieving a goal), reference (information) and explanation (understanding). Keeping these types separate makes documentation easier to write, maintain and use.

GitHub's documentation lists what the project does, why it is useful, how users can get started, where they can get help, and who maintains and contributes to it. Keep it short, with a working quick start near the top, and link to deeper documentation.

Start with a short first line written as an imperative that makes sense on its own in the history. In the body, explain the problem, the approach, alternatives you considered and how you tested. Re-read it before merging so it still matches the final change.

Mostly active. Google's course recommends the active voice most of the time and the passive voice sparingly. Active sentences name who performs an action, which matters in instructions where the reader needs to know whether they or the system does something.

Use it as an editor rather than the author. AI assistants are good at spotting unclear sentences, undefined terms and inconsistent naming, but they lack your context and can add wrong details. Draft yourself, ask for critique, and verify every fact before publishing.