SKILL.md
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).