Tech Documentation Skill

Technical documentation writing expertise, providing comprehensive methodology and templates for producing high-quality technical documentation.

When to Use

Trigger scenarios — use this skill when the user asks to:

Write API documentation or developer guides
Create architecture design documents
Produce deployment or operations manuals

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

Worked Example: Documenting POST /login

Task: "Write API documentation for a POST /login endpoint."

Step 1 — Scope with the requester. Audience: third-party integrators. Structure follows references/api-doc-template.md; responses use the {code, message, data, request_id, timestamp} envelope shown below (define it explicitly if your project uses a different one).

Step 2 — Write the document.

POST /login

Authenticates a user and returns an access token.

Request body

Field	Type	Required	Description
username	string	yes	Account name or email
password	string	yes	Account password (TLS required)

{
  "username": "john_doe",
  "password": "s3cret!"
}

Response 200

{
  "code": 0,
  "message": "Success",
  "data": { "token": "eyJhbGciOi...", "expires_in": 3600 },
  "request_id": "req_abc123",
  "timestamp": "2026-10-08T10:30:00Z"
}

Response 401 — invalid credentials

{
  "code": 40101,
  "message": "Invalid username or password",
  "request_id": "req_def456",
  "timestamp": "2026-10-08T10:30:01Z"
}

cURL

curl -X POST https://api.example.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username": "john_doe", "password": "s3cret!"}'

Step 3 — Self-check against the Documentation Quality Checklist below (endpoint, params, success + error responses, runnable example, all present).

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