documentation-standards

制定清晰、全面的技术文档编写标准与最佳实践。

SKILL.md

--- frontmatter

name: documentation-standards
description: Standards and best practices for writing clear, comprehensive technical documentation.
license: MIT

Documentation Standards Skill

This skill provides guidelines for creating and maintaining high-quality documentation across all repositories in the organization.

Instructions

Follow these documentation standards:

•
README Requirements
- •Include a clear project description
- •Provide installation and setup instructions
- •Document usage examples
- •List prerequisites and dependencies
- •Include contribution guidelines
- •Add license information
•
Code Documentation
- •Document public APIs and interfaces
- •Use consistent documentation format (JSDoc, docstrings, etc.)
- •Explain complex algorithms or business logic
- •Document parameters, return values, and exceptions
- •Keep comments up-to-date with code changes
•
Architecture Documentation
- •Document high-level system architecture
- •Explain key design decisions
- •Maintain architecture decision records (ADRs)
- •Document data flows and integrations
- •Include diagrams where helpful
•
User Documentation
- •Write for your audience (technical vs. non-technical)
- •Use clear, concise language
- •Include step-by-step instructions
- •Provide troubleshooting guides
- •Keep documentation versioned with releases
•
Documentation Quality
- •Keep documentation concise and focused
- •Use proper formatting and structure
- •Include code examples where appropriate
- •Verify all links work
- •Use correct grammar and spelling
•
Maintenance
- •Update documentation when features change
- •Remove outdated information
- •Review documentation regularly
- •Accept documentation contributions

Usage

This skill helps ensure consistent, high-quality documentation across all organization repositories.