majiayu000 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
- Diátaxis Alignment — Distinguish between tutorials, how-to guides, explanations, and references.
- Clear Structure — Use logical heading hierarchies and consistent formatting for easy navigation.
- Audience Awareness — Write for the specific reader (e.g., contributor, operator, or end-user).
- Actionable Content — Ensure instructions are clear, step-by-step, and testable.
- 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.