Documentation Standards
npx machina-cli add skill hoangnguyen0403/agent-skills-standard/documentation --openclawFiles (1)
SKILL.md
1.9 KB
Documentation Standards - High-Density Standards
Essential rules for code comments, READMEs, and technical documentation.
Priority: P2 (MAINTENANCE)
Essential rules for maintaining proper code comments, READMEs, and technical documentation.
📝 Code Comments (Inline Docs)
- "Why" over "What": Comments should explain non-obvious intent. Code should describe the logic.
- Docstrings: Use triple-slash (Dart/Swift) or standard JSDoc (TS/JS) for all public functions and classes.
- Maintenance: Delete "commented-out" code immediately; use Git history for retrieval.
- TODOs: Use
TODO(username): descriptionorFIXMEto track technical debt with ownership.
📖 README Essentials
- Mission: Clear one-sentence summary of the project purpose.
- Onboarding: Provide exact Prerequisites (runtimes), Installation steps, and Usage examples.
- Maintainability: Document inputs/outputs, known quirks, and troubleshooting tips.
- Up-to-Date: Documentation is part of the feature; keep it synchronized with code changes.
🏛 Architectural & API Docs
- ADRs: Document significant architectural changes and the "Why" in
docs/adr/. - Docstrings: Document Classes and Functions with clear descriptions of Args, Returns, and usage Examples (
>>>). - Diagrams: Use Mermaid.js inside Markdown to provide high-level system overviews.
🚀 API Documentation
- Self-Documenting: Use Swagger/OpenAPI for REST or specialized doc generators for your language.
- Examples: Provide copy-pasteable examples for every major endpoint or utility.
- Contract First: Define the interface before the implementation.
Source
git clone https://github.com/hoangnguyen0403/agent-skills-standard/blob/develop/.github/skills/common/documentation/SKILL.mdView on GitHub Overview
Documentation Standards defines essential rules for comments, READMEs, and architecture/API docs to improve maintainability and onboarding. It emphasizes explaining intent with comments, using proper docstrings, keeping READMEs current, and documenting ADRs and APIs.
How This Skill Works
It codifies practice across code comments, READMEs, ADRs, and API docs. It prescribes docstring formats, non-obvious intent in comments, and diagram-based system overviews using Mermaid, plus a contract-first approach for APIs.
When to Use It
- Kick off a project by defining documentation rules and templates.
- Refactor legacy code by aligning comments, READMEs, and ADRs to standards.
- Onboard new contributors with consistent docs, examples, and usage guidance.
- Document architectural changes (ADRs) and high-level diagrams for visibility.
- Develop and maintain self-documenting APIs using OpenAPI or language-specific docs.
Quick Start
- Step 1: Inventory codebase comments, READMEs, and ADRs to identify gaps.
- Step 2: Establish doc standards files (style, templates, ADRs) and add Mermaid diagrams.
- Step 3: Apply standards to new code and update existing docs; set PR checks.
Best Practices
- Write 'Why' over 'What' in inline comments to explain intent.
- Document public APIs with clear docstrings and usage examples.
- Do not keep commented-out code; remove it and rely on Git history.
- Keep READMEs current with mission, prerequisites, installation, usage, inputs/outputs, and troubleshooting.
- Include ADRs and Mermaid diagrams for architectural decisions and system overview.
Example Use Cases
- Public API doc written with OpenAPI specs and example requests.
- New module includes docstrings for all functions/classes with Args/Returns.
- ADR documenting a major architectural decision and its rationale.
- README that lists prerequisites, install steps, and usage examples.
- Mermaid diagram illustrating system architecture in docs.
Frequently Asked Questions
Add this skill to your agents
