- name
- technical-writing
- description
- Guide for creating effective internal technical documentation (READMEs, ADRs, Contribution Guides). Use this skill when the user asks to write, refactor, or improve internal project documentation.
Technical Writing for Developers
This skill provides best practices and templates for writing clear, maintainable internal documentation.
Core Principles
- Audience Awareness: Write for your teammates (and your future self). Assume they know *how* to code, but not *why* this specific code exists.
- Active Voice: Use active voice for instructions.
* *Bad*: "The server should be started by running..." * *Good*: "Run npm start to start the server."
- Single Source of Truth: Don't duplicate code logic in comments. Explain *why*, not *what*.
- Front-Load Context: Put the most important information (what is this? how do I run it?) at the top.
Common Artifacts & Templates
1. README.md (Root or Component)
Every significant directory should have a README.
# [Project/Component Name]
[One-sentence description of what this is].
## Prerequisite
* Node.js >= 20
* [Other dependency]
## Quick Start
npm install npm run dev
## Architecture
[Brief explanation of how it works. Diagrams are great.]
## Key Concepts
* **Concept A**: Definition...
* **Concept B**: Definition...2. Architecture Decision Record (ADR)
Use for significant technical decisions.
# [Short Title]
* **Status**: [Proposed | Accepted | Deprecated]
* **Date**: YYYY-MM-DD
* **Deciders**: [List names]
## Context
[Describe the problem and constraints.]
## Decision
[Describe what we are doing.]
## Consequences
* [Positive consequence]
* [Negative consequence / Trade-off]Style Guide
- Headers: Use Sentence case for headers (e.g., "Getting started" not "Getting Started").
- Code Blocks: Always specify the language for syntax highlighting (e.g., \
\\`typescript). - Lists: Use bullet points for options, numbered lists for steps.
- Links: Use relative links
[Link](./path/to/file)so they work in the repo browser.
Review Checklist
Before committing documentation:
- [ ] Completeness: did I cover "how to run" and "how to test"?
- [ ] Freshness: Did I actually run the commands in a fresh terminal?
- [ ] Links: Do all internal links work?
- [ ] Grammar: Is it readable? (Use a spell checker).