technical-writing

Technical Writing Skill

Good documentation is the difference between a project that scales and one that stalls. Write for the reader who has zero context.

1. When to Apply This Skill

Trigger conditions:

• Writing or updating a README
• Creating API documentation
• Writing architecture decision records (ADRs)
• Building runbooks or incident playbooks
• Creating onboarding/developer guides
• Reviewing documentation for clarity

2. Document Types and Templates

Document Provenance Frontmatter

All descriptive Markdown docs must follow .github/instructions/document-frontmatter.instructions.md.

• New docs: include Original Author, Creation Date, and Creating Model in YAML frontmatter.
• Updated docs: preserve those original fields and add or update Last Author, Last Updated, and Last Model Used.
• Use full ISO 8601 UTC timestamps for Creation Date and Last Updated values.
• Merge these fields into existing frontmatter instead of replacing document-specific metadata.

README Structure

Every project README follows this order:

# Project Name
One-sentence description of what this does and who it's for.

## Quick Start
Minimum steps to run the project locally (≤5 commands).

## Prerequisites
- Runtime versions (Python 3.12+, Node 22+)
- Required tools (Docker, pnpm)
- Required accounts/access

## Installation
Step-by-step setup with copy-pasteable commands.

## Usage
Common tasks with examples.

## Architecture
Brief overview with a diagram (link to detailed docs).

## Contributing
How to submit changes, run tests, and follow conventions.

## License

Rules:

• Quick Start must work on a fresh machine in under 5 minutes
• Every command must be copy-pasteable (no <placeholder> without explanation)
• Test the README by following it literally on a clean environment

Architecture Decision Record (ADR)

# ADR-{NNN}: {Decision Title}

## Status
Accepted | Superseded by ADR-{NNN} | Deprecated

## Context
What problem are we solving? What constraints exist?

## Decision
What did we decide and why?

## Alternatives Considered
| Option | Pros | Cons | Why Not |
|--------|------|------|---------|

## Consequences
What changes as a result? What new constraints are introduced?