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.