technical-writing_skill

Overview

This skill guides engineers to create effective internal technical documentation like READMEs, ADRs, and contribution guides. It focuses on clarity, maintainability, and ensuring teammates can quickly understand purpose, setup, and decisions. The guidance is practical and ready to apply to project directories or components.

How this skill works

The skill inspects documentation needs and provides templates, style rules, and a review checklist tailored to internal developer audiences. It recommends what to include at the top of a file, how to structure decision records, and how to keep docs up to date without duplicating code. Use it to draft, refactor, or validate documentation for repositories and components.

When to use it

• Creating a new project or adding a major component and you need a clear README.
• Documenting a significant architectural decision that should be tracked over time.
• Improving an existing README to reduce developer onboarding time.
• Writing contribution or setup guides for internal collaborators.
• Preparing documentation for handoff or post-release maintenance.

Best practices

• Write for your teammates and future you: explain why, not just what.
• Front-load context: put purpose and quick-start steps at the top.
• Use active voice and short, actionable commands.
• Keep a single source of truth: avoid copying code into docs.
• Use consistent header sentence case and language-specified code blocks.
• Run commands in a fresh environment before publishing to ensure accuracy.

Example use cases

• A root README that explains project purpose, prerequisites, quick start, and architecture.
• A component-level README that describes responsibilities, public API, and local dev steps.
• An ADR to record choosing a database, including context, decision, and trade-offs.
• A CONTRIBUTING guide for internal contributors with branching, testing, and PR rules.
• A checklist run before merging: completeness, links, freshness, and grammar.