technical-writing-clarity

Technical Writing for Clarity

Principles:

• Lead with the purpose: What is this document for and who is it for?
• One idea per paragraph. Long paragraphs hide key information.
• Use active voice: Run the script not The script should be run.
• Concrete over abstract: Show an example rather than describing it abstractly.
• Avoid jargon you have not defined unless the audience definitely knows it.

Structure for runbooks/how-tos:

1. Overview (1–2 sentences)
2. Prerequisites
3. Steps (numbered, imperative)
4. Verification / expected output
5. Troubleshooting

Anti-patterns: Documenting what without why, outdated examples, walls of text without headers.