Technical Writing Clarity

Use this skill when writing documentation, READMEs, technical specs, runbooks, or any text that explains a system or process to other engineers. Apply before writing any developer-facing document.

gabrielmoreira Updated 17 repo stars

File contents

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.

gabrielmoreira/agent-skills-mirror/tree/main/mirrors/repos/aiming-lab@MetaClaw/memory_data/skills/technical-writing-clarity commit ded209c784

Frequently asked questions

npx skillmds@latest add gabrielmoreira/technical-writing-clarity