documentation-standards
How user-facing and internal documentation should be written and maintained.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for creating and maintaining high-quality technical documentation. It establishes clear standards for user-facing guides, internal architecture docs, and inline comments, focusing on clarity, active voice, and consistent structure to improve knowledge sharing and software maintainability.
Use Cases
- Standardizing Technical Writing: Establish a consistent voice, tone, and formatting across all product documentation to enhance professional branding and readability.
- Internal Knowledge Management: Define clear structures for architecture docs and ADRs (Architecture Decision Records) to ensure system design rationale is preserved for future developers.
- User Onboarding and Support: Create structured feature documentation including configuration, examples, and troubleshooting to reduce support tickets and improve user self-service.
- Documentation Maintenance: Implement a workflow for incremental updates that ensures documentation evolves alongside code changes, preventing outdated or misleading information.
| name | documentation-standards |
|---|---|
| description | How user-facing and internal documentation should be written and maintained. |
Documentation Standards
Types of Documentation
User-facing docs
- Explain features, configuration, and usage.
- Assume no access to source code.
Internal docs
- Capture system behavior, architecture, and decisions for developers.
- Include rationale and trade-offs.
Inline docs / comments
- Explain non-obvious implementation details or constraints.
Style & Tone
- Clear, concise, and concrete.
- Prefer active voice and simple sentences.
- Avoid unexplained acronyms and internal-only jargon.
Structure Guidelines
Feature Docs
- Overview
- Use cases
- Configuration and defaults
- Examples
- Limitations and edge cases
- Troubleshooting
Architecture Docs
- High-level diagram (or description)
- Components and responsibilities
- Data flows and interactions
- Trade-offs and constraints
- Links to related RFCs or ADRs
Maintenance Rules
- Documentation must be updated as part of behavior changes.
- Prefer small, incremental doc updates rather than large rewrites.
- Link docs to relevant issues or tickets where useful.
Formatting
- Use Markdown (
.md) for text docs. - Use consistent heading levels and lists.
- Include code blocks with language tags.