# Documentation Writing

> Write clear technical documentation - READMEs, ADRs, runbooks, API docs

- Skill: `majiayu000/documentation-writing-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/documentation-writing-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/documentation-writing-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/documentation-writing-2

---


# Skill: documentation-writing

## What I do

I provide expertise in writing clear, structured technical documentation. I focus on making complex systems understandable through well-organized READMEs, Architecture Decision Records (ADRs), runbooks, and installation guides following the Diátaxis framework.

## When to use me

- Creating or updating a project's README or contribution guide
- Documenting architectural decisions through ADRs
- Writing operational runbooks and troubleshooting guides
- Structuring technical manuals or internal wiki pages

## Core principles

1.  **Diátaxis Alignment** — Distinguish between tutorials, how-to guides, explanations, and references.
2.  **Clear Structure** — Use logical heading hierarchies and consistent formatting for easy navigation.
3.  **Audience Awareness** — Write for the specific reader (e.g., contributor, operator, or end-user).
4.  **Actionable Content** — Ensure instructions are clear, step-by-step, and testable.
5.  **Docs-as-Code** — Keep documentation close to the code, versioned, and reviewed.

## Patterns & examples

### Standard README Structure
- **Title & Badges**: Project name and status.
- **Summary**: What the project does and who it's for.
- **Getting Started**: Prerequisites and installation steps.
- **Usage**: Basic examples to get the user running.
- **Contributing**: Link to CONTRIBUTING.md.
- **License**: Clear declaration.

### ADR Template Pattern
- **Title**: Short and descriptive (e.g., "ADR 005: Using PostgreSQL for Persistence").
- **Context**: The problem and constraints.
- **Options**: Possible solutions considered.
- **Decision**: The chosen path and rationale.
- **Consequences**: Expected impact (good and bad).

## Anti-patterns to avoid

-   ❌ **The README Graveyard** — Documentation that hasn't been updated in months or years.
-   ❌ **Implicit Prerequisites** — Failing to list the exact tools and versions needed to run the project.
-   ❌ **Wall of Text** — Large blocks of prose without headings or lists to break them up.
-   ❌ **Undefined Acronyms** — Using internal or niche acronyms without explanation.

## KB Reference

`~/vaults/baphled/3. Resources/Knowledge Base/AI Development System/Skills/Communication-Writing/Documentation Writing.md`

## Related skills

-   `api-documentation` — For specific endpoint and schema documentation.
-   `writing-style` — To maintain a professional and consistent voice.
-   `proof-reader` — For final clarity and correctness checks.
-   `architecture` — For documenting high-level system designs.