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

• Google Developer Documentation Style Guide

• Microsoft Writing Style Guide

• Write the Docs

Version: 1.0.0 Last Updated: December 2024 Maintainer: MindForge Team