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

Information is accurate and complete
Logic is clear and coherent
Examples are realistic and usable
Terminology is consistent and standardized

Readability

Language is concise and clear
Structure is well-organized
Formatting is unified and attractive
Diagrams are clear and easy to understand

Maintainability

Version information is clear
Change records are complete
Contact information is accurate
Regular review and updates

Accessibility

Table of contents navigation is clear
Search functionality is complete
Links are valid and accurate
Multiple formats are supported

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