Tech Documentation Skill
Technical documentation writing expertise, providing comprehensive methodology and templates for producing high-quality technical documentation.
Overview
This is a comprehensive skill module focused on technical documentation writing, covering standards, templates, and best practices for various types of technical documentation to help teams produce high-quality, easy-to-understand, and maintainable documentation.
Core Capabilities
1. API Documentation
- OpenAPI/Swagger Specifications
- RESTful API Documentation
- GraphQL Documentation
- gRPC Interface Documentation
- API Change Logs
- Authentication and Authorization Documentation
2. Architecture Documentation
- Architecture Design Documents (ADD)
- Architecture Decision Records (ADR)
- System Architecture Diagrams (C4 Model, UML)
- Technology Selection Reports
- Architecture Evolution Roadmaps
3. Detailed Design Documents
- Module Design Documents
- Database Design Documents
- Interface Design Documents
- Algorithm Design Specifications
- Sequence Diagrams/Flowcharts
4. Deployment and Operations Documentation
- Deployment Manuals
- Operations Manuals
- Incident Response Manuals
- Monitoring and Alerting Configuration
- Performance Optimization Guides
- Backup and Recovery Procedures
5. User Manuals
- Product User Manuals
- Quick Start Guides
- Frequently Asked Questions (FAQ)
- Troubleshooting Guides
- Best Practices
6. Developer Documentation
- Contributing Guidelines (CONTRIBUTING.md)
- Coding Standards
- Development Environment Setup
- Testing Guides
- Release Processes
7. Project Management Documentation
- Project Plans
- Requirements Documents
- Test Plans
- Release Notes
- Change Logs (CHANGELOG)
8. Knowledge Base Documentation
- Technical Blog Posts
- Case Studies
- Problem Summaries
- Learning Notes
Documentation Principles
1. The 5C Principles
- Clear: Concise language, clear logic
- Concise: Avoid redundancy, get to the point
- Complete: Comprehensive information covering all needs
- Correct: Accurate content, verified and tested
- Consistent: Unified style, standardized terminology
2. Audience-Oriented
- Understand target audience (developers, operations, product, users)
- Use language and concepts familiar to the audience
- Provide information at different levels (overview → detailed)
- Include practical examples and best practices
3. Structured Organization
- Clear hierarchical structure
- Unified format and style
- Table of contents and navigation
- Cross-references
4. Maintainability
- Version control
- Change records
- Regular review and updates
- Feedback mechanisms
Documentation Templates
API Documentation Template (OpenAPI format, endpoints, error codes, changelog): see references/api-doc-template.md
Architecture Design Document Template (overview, requirements, architecture, tech stack, data, deployment): see references/architecture-template.md
Deployment Documentation Template (environment, prerequisites, deployment steps, rollback, monitoring): see references/deployment-template.md
Use Cases
New Project Launch
Create complete documentation system for new project:
- README.md
- API documentation
- Architecture design document
- Deployment documentation
- Contributing guidelines
API Design Review
Write API design documentation, including:
- Interface definitions
- Data models
- Error handling
- Security authentication
System Delivery
Prepare system delivery documentation package:
- System architecture documentation
- Deployment and operations manual
- User manual
- Incident response manual
Knowledge Management
Technical solution summary:
- Problem analysis
- Solutions
- Technical decisions
- Lessons learned
Integration Examples
Using in Agent
{
"agent": "tech-writer",
"skills": [
"tech-documentation",
"system-architecture",
"api-design"
]
}
Referencing in Conversation
@tech-documentation Please create complete documentation for this API
Documentation Quality Checklist
Content Quality
Readability
Maintainability
Accessibility
Recommended Tools
Documentation Writing
- Markdown Editors: Typora, VS Code
- API Documentation: Swagger Editor, Postman
- Diagram Tools: Draw.io, PlantUML, Mermaid
- Screenshot Tools: Snipaste, Xnip
Documentation Hosting
- Static Sites: GitBook, Docusaurus, VuePress
- Team Collaboration: Confluence, Notion
- Version Control: Git, GitHub/GitLab
Documentation Generation
- API Documentation: Swagger/OpenAPI, ApiDoc
- Code Documentation: JavaDoc, JSDoc, Sphinx
- README Generation: readme-md-generator
Learning Resources
Recommended Books
- "Technical Writing: A Practical Guide"
- "Docs for Developers"
- "The Documentation Compendium"
Online Resources
Version: 1.0.0
Last Updated: December 2024
Maintainer: MindForge Team
1---2name: tech-documentation3description: Technical documentation writing skill covering API docs, architecture documentation, deployment guides, and various technical writing best practices. Use this skill when creating technical documentation, writing API documentation, creating architecture design documents, or need templates for deployment and operations manuals.4---5
6# Tech Documentation Skill
7
8Technical documentation writing expertise, providing comprehensive methodology and templates for producing high-quality technical documentation.
9
10## Overview
11
12This is a comprehensive skill module focused on technical documentation writing, covering standards, templates, and best practices for various types of technical documentation to help teams produce high-quality, easy-to-understand, and maintainable documentation.
13
14## Core Capabilities
15
16### 1. API Documentation
17- **OpenAPI/Swagger Specifications**
18- **RESTful API Documentation**
19- **GraphQL Documentation**
20- **gRPC Interface Documentation**
21- **API Change Logs**
22- **Authentication and Authorization Documentation**
23
24### 2. Architecture Documentation
25- **Architecture Design Documents (ADD)**
26- **Architecture Decision Records (ADR)**
27- **System Architecture Diagrams** (C4 Model, UML)
28- **Technology Selection Reports**
29- **Architecture Evolution Roadmaps**
30
31### 3. Detailed Design Documents
32- **Module Design Documents**
33- **Database Design Documents**
34- **Interface Design Documents**
35- **Algorithm Design Specifications**
36- **Sequence Diagrams/Flowcharts**
37
38### 4. Deployment and Operations Documentation
39- **Deployment Manuals**
40- **Operations Manuals**
41- **Incident Response Manuals**
42- **Monitoring and Alerting Configuration**
43- **Performance Optimization Guides**
44- **Backup and Recovery Procedures**
45
46### 5. User Manuals
47- **Product User Manuals**
48- **Quick Start Guides**
49- **Frequently Asked Questions (FAQ)**
50- **Troubleshooting Guides**
51- **Best Practices**
52
53### 6. Developer Documentation
54- **Contributing Guidelines** (CONTRIBUTING.md)
55- **Coding Standards**
56- **Development Environment Setup**
57- **Testing Guides**
58- **Release Processes**
59
60### 7. Project Management Documentation
61- **Project Plans**
62- **Requirements Documents**
63- **Test Plans**
64- **Release Notes**
65- **Change Logs** (CHANGELOG)
66
67### 8. Knowledge Base Documentation
68- **Technical Blog Posts**
69- **Case Studies**
70- **Problem Summaries**
71- **Learning Notes**
72
73## Documentation Principles
74
75### 1. The 5C Principles
76- **Clear**: Concise language, clear logic
77- **Concise**: Avoid redundancy, get to the point
78- **Complete**: Comprehensive information covering all needs
79- **Correct**: Accurate content, verified and tested
80- **Consistent**: Unified style, standardized terminology
81
82### 2. Audience-Oriented
83- Understand target audience (developers, operations, product, users)
84- Use language and concepts familiar to the audience
85- Provide information at different levels (overview → detailed)
86- Include practical examples and best practices
87
88### 3. Structured Organization
89- Clear hierarchical structure
90- Unified format and style
91- Table of contents and navigation
92- Cross-references
93
94### 4. Maintainability
95- Version control
96- Change records
97- Regular review and updates
98- Feedback mechanisms
99
100## Documentation Templates
101
102> **API Documentation Template** (OpenAPI format, endpoints, error codes, changelog): see [references/api-doc-template.md](references/api-doc-template.md)
103
104> **Architecture Design Document Template** (overview, requirements, architecture, tech stack, data, deployment): see [references/architecture-template.md](references/architecture-template.md)
105
106> **Deployment Documentation Template** (environment, prerequisites, deployment steps, rollback, monitoring): see [references/deployment-template.md](references/deployment-template.md)
107
108## Use Cases
109
110### New Project Launch
111```
112Create complete documentation system for new project:
113- README.md
114- API documentation
115- Architecture design document
116- Deployment documentation
117- Contributing guidelines
118```
119
120### API Design Review
121```
122Write API design documentation, including:
123- Interface definitions
124- Data models
125- Error handling
126- Security authentication
127```
128
129### System Delivery
130```
131Prepare system delivery documentation package:
132- System architecture documentation
133- Deployment and operations manual
134- User manual
135- Incident response manual
136```
137
138### Knowledge Management
139```
140Technical solution summary:
141- Problem analysis
142- Solutions
143- Technical decisions
144- Lessons learned
145```
146
147## Integration Examples
148
149### Using in Agent
150```json
151{
152 "agent": "tech-writer",
153 "skills": [
154 "tech-documentation",
155 "system-architecture",
156 "api-design"
157 ]
158}
159```
160
161### Referencing in Conversation
162```
163@tech-documentation Please create complete documentation for this API
164```
165
166## Documentation Quality Checklist
167
168### Content Quality
169- [ ] Information is accurate and complete
170- [ ] Logic is clear and coherent
171- [ ] Examples are realistic and usable
172- [ ] Terminology is consistent and standardized
173
174### Readability
175- [ ] Language is concise and clear
176- [ ] Structure is well-organized
177- [ ] Formatting is unified and attractive
178- [ ] Diagrams are clear and easy to understand
179
180### Maintainability
181- [ ] Version information is clear
182- [ ] Change records are complete
183- [ ] Contact information is accurate
184- [ ] Regular review and updates
185
186### Accessibility
187- [ ] Table of contents navigation is clear
188- [ ] Search functionality is complete
189- [ ] Links are valid and accurate
190- [ ] Multiple formats are supported
191
192## Recommended Tools
193
194### Documentation Writing
195- **Markdown Editors**: Typora, VS Code
196- **API Documentation**: Swagger Editor, Postman
197- **Diagram Tools**: Draw.io, PlantUML, Mermaid
198- **Screenshot Tools**: Snipaste, Xnip
199
200### Documentation Hosting
201- **Static Sites**: GitBook, Docusaurus, VuePress
202- **Team Collaboration**: Confluence, Notion
203- **Version Control**: Git, GitHub/GitLab
204
205### Documentation Generation
206- **API Documentation**: Swagger/OpenAPI, ApiDoc
207- **Code Documentation**: JavaDoc, JSDoc, Sphinx
208- **README Generation**: readme-md-generator
209
210## Learning Resources
211
212### Recommended Books
213- "Technical Writing: A Practical Guide"
214- "Docs for Developers"
215- "The Documentation Compendium"
216
217### Online Resources
218- [Google Developer Documentation Style Guide](https://developers.google.com/style)
219- [Microsoft Writing Style Guide](https://docs.microsoft.com/style-guide/)
220- [Write the Docs](https://www.writethedocs.org/)
221
222---
223
224**Version**: 1.0.0
225**Last Updated**: December 2024
226**Maintainer**: MindForge Team
majiayu000