write-tech-docs_skill

Overview

This skill applies proven editorial principles to write and review technical documentation, focusing on clarity, scannability, and user value. It prioritizes leading with outcomes, removing redundancy, and providing consolidated, copy‑pasteable examples. Use it to shape READMEs, API docs, quickstarts, and troubleshooting guides that get users productive fast.

How this skill works

When invoked, the skill identifies the document type and applies the matching pattern (strict for READMEs, precise for API docs, more hand‑holding for troubleshooting). It restructures opening sections to lead with user value, converts feature lines into benefits, consolidates examples into single runnable blocks, and removes hedging and obvious statements. The output is a revised, ready‑to‑publish draft plus a checklist of editorial checks applied.

When to use it

• Writing a new README or Quickstart that must convert quickly
• Rewriting API documentation to be precise and machine‑readable
• Consolidating scattered code examples into a single runnable block
• Reviewing docs to remove redundancy and hedging
• Preparing troubleshooting guides that need multiple debugging approaches

Best practices

• Start each document with a one‑sentence value proposition and a one‑sentence mechanism summary
• Show the recommended path; list alternatives in a separate options section
• Use action‑first feature lines (verb + user benefit + optional detail)
• Consolidate examples into one conceptual code block per task
• Remove obvious instructions and future‑tense hedging; every sentence must add new info

Example use cases

• Transform a verbose README into a one‑paragraph value proposition plus benefits and a quick example
• Rewrite an API reference to include return types, error conditions, and exact option lists
• Create a Quickstart with a single runnable code block and minimal setup steps
• Review a troubleshooting guide to add clear steps and acceptable fallback options
• Audit docs to ensure parallel lists, consistent terminology, and active voice