Docs Write Skill
Relevant source files
The following files were used as context for generating this wiki page:The docs-write skill is a workflow-based capability for AI agents to create or update technical documentation. It ensures that all documentation adheres to a clear style, structure, and set of standards defined within the project. This skill is triggered for various tasks, including documenting new features, updating API endpoints, creating Architectural Decision Records (ADRs), or addressing feedback from code reviews.
As a "workflow skill," it does not have a single executable script. Instead, it provides a structured set of instructions for an agent to follow, relying heavily on the references/documentation-guide.md as its source of truth for all standards and patterns. The process is designed to be systematic, starting with understanding requirements and ending with verification using the docs-check skill.
Sources: skills/docs-write/SKILL.md:1-5, skills/README.md:13-14, AGENTS.md:27-29
Core Workflow
The docs-write skill follows a mandatory, sequential workflow to ensure high-quality and consistent documentation. The agent must read the documentation-guide.md before any writing commences.
Sources: skills/docs-write/SKILL.md:13-16
The diagram below illustrates the standard documentation writing process.
Sources: skills/docs-write/SKILL.md:18-53
Workflow Steps
- Read the Guide: The first and most critical step is to load and read
references/documentation-guide.md. This file contains all standards and must be consulted before proceeding. - Determine Doc Type: Based on the guide, classify the documentation as a tutorial, how-to guide, reference, or explanation.
- Review Style: Consult the "Style and Voice" and "Structure and Skimmability" sections of the guide.
- Draft Content: Write the documentation, including code examples and following the prescribed structure.
- Add Visuals: If the content is complex, add diagrams. Use Mermaid for inline visuals and PlantUML for diagrams that are reused across multiple documents.
- Follow Templates: For specialized types like API documentation, ADRs, or runbooks, adhere to the specific templates provided in the guide.
- Final Review: Cross-reference related documents and ensure all checklist items from the guide are met.
- Verify: Execute
bash skills/docs-check/scripts/check-docs.shto ensure the documentation is complete and meets project standards.
Sources: skills/docs-write/SKILL.md:18-53
Documentation Standards
All documentation must adhere to the principles and structures defined in documentation-guide.md.
Sources: skills/docs-write/references/documentation-guide.md
Document Types (Divio Framework)
The project categorizes documentation into four types based on the Divio framework.
| Type | Orientation | Description |
|---|---|---|
| Tutorial | Learning-oriented | A step-by-step guide for beginners to achieve a goal. |
| How-to | Goal-oriented | A series of steps to solve a specific, task-focused problem. |
| Reference | Fact-oriented | Technical descriptions of the machinery, such as API endpoints or configuration. |
| Explanation | Understanding-oriented | Conceptual documentation that clarifies and illuminates a particular topic. |
Sources: skills/docs-write/references/documentation-guide.md:33-38, skills/docs-write/SKILL.md:23-28
Style and Structure
- Voice: Use active voice, the second person ("you"), and consistent terminology.
- Clarity: Prefer clear, concise, and direct language. Keep sentences short.
- Skimmability: Employ a clear heading hierarchy (H2/H3), short paragraphs, lists, and tables to allow for quick scanning. Start with the purpose and outcome.
Sources: skills/docs-write/references/documentation-guide.md:24-31
Visuals and Diagrams
The choice between embedding a diagram or linking to a separate file depends on its usage and context.
This decision flow guides the choice of diagramming tool.
- Mermaid: Used for inline diagrams (e.g., ER diagrams, sequence diagrams) embedded directly in Markdown files. This is the standard for visuals that enhance a single document.
- PlantUML: Used for diagrams stored as separate
.pumlfiles. This is preferred for complex diagrams that are referenced from multiple documents or need to be version-controlled separately.
Sources: skills/docs-write/references/documentation-guide.md:104-129
Specialized Documentation
API Documentation
API documentation must be comprehensive and include the following elements:
- Authentication methods
- All available endpoints
- Request and response formats with examples
- Error codes and their meanings
- Prominent notes on breaking changes and versioning
Sources: skills/docs-write/references/documentation-guide.md:131-134, skills/docs-write/SKILL.md:45-49
ADRs and Runbooks
Architectural Decision Records (ADRs) and Runbooks follow specific templates to ensure consistency.
| Document | Required Content |
|---|---|
| ADR | Problem context, the decision made, and the consequences of the decision. |
| Runbook | Trigger conditions, pre-checks, execution steps, validation procedures, rollback steps, and contact points. |
Sources: skills/docs-write/references/documentation-guide.md:136-139, skills/docs-write/SKILL.md:50-54
Integration with Other Skills
The docs-write skill is part of a larger "docs-as-code" ecosystem and integrates tightly with other skills, particularly docs-check.
Sources: skills/docs-write/SKILL.md:61-64
The Docs Check & Write Loop
The docs-check skill is typically run after code changes to identify what documentation needs to be updated. Its output serves as the input for the docs-write skill. After writing, docs-check is run again for verification.
This sequence diagram shows the typical interaction between a developer (or orchestrator agent), docs-check, and docs-write.
The docs-check.sh script categorizes code changes and suggests relevant documentation files to review. It checks for modifications in areas like:
- Database/Schema
- API endpoints
- UI Components
- Configuration files
- Authentication logic
Sources: skills/docs-check/scripts/check-docs.sh:124-194, skills/docs-check/SKILL.md:11-17
Summary
The docs-write skill provides a robust, guide-driven framework for producing and maintaining high-quality technical documentation. It operationalizes a "docs-as-code" philosophy by defining a clear, repeatable workflow that integrates with other development tools and skills. By mandating the use of a central documentation-guide.md and a final verification step with docs-check, it ensures that all documentation remains consistent, accurate, and synchronized with the codebase.
Sources: skills/docs-write/SKILL.md, skills/docs-write/references/documentation-guide.md:231-240