--- id: sm-technical-writing name: "technical-writing" url: https://skills.yangsir.net/skill/sm-technical-writing author: supercent-io domain: writing tags: ["documentation", "user-manuals", "api-guides", "markdown", "confluence"] install_count: 11700 rating: 4.50 (468 reviews) github: https://github.com/supercent-io/skills-template --- # technical-writing > 该技能专注于撰写技术规范、架构文档、系统设计、运行手册和操作指南，旨在清晰准确地传达复杂的技术信息。 **Stats**: 11,700 installs · 4.5/5 (468 reviews) ## Before / After 对比 ### 从模糊到清晰的技术文档 | Metric | Before | After | Change | |---|---|---|---| | - | - | - | - | | - | - | - | - | | - | - | - | - | | - | - | - | - | ## Readme # technical-writing Technical Writing When to use this skill Writing technical specifications Creating architecture documentation Documenting system designs Writing runbooks and operational guides Creating developer documentation API documentation User manuals and guides Release notes and changelogs Instructions Step 1: Understand your audience Developer audience: Focus on implementation details Include code examples Technical terminology is okay Show how, not just what DevOps/Operations audience: Focus on deployment and maintenance Include configuration examples Emphasize monitoring and troubleshooting Provide runbooks Manager/Stakeholder audience: High-level overview Business impact Minimal technical jargon Focus on outcomes End user audience: Simple, clear language Step-by-step instructions Visual aids (screenshots, videos) FAQ section Step 2: Choose the right document type Technical Specification: # [Feature Name] Technical Specification ## Overview Brief description of what this spec covers ## Problem Statement What problem are we solving? ## Goals and Non-Goals ### Goals - Goal 1 - Goal 2 ### Non-Goals - What we're explicitly not doing ## Solution Design ### High-Level Architecture ### Data Models ### API Contracts ### User Interface ## Implementation Plan ### Phase 1 ### Phase 2 ## Testing Strategy ## Security Considerations ## Performance Considerations ## Monitoring and Alerting ## Rollout Plan ## Rollback Plan ## Open Questions ## References Architecture Document: # System Architecture ## Overview High-level system description ## Architecture Diagram [Insert diagram] ## Components ### Component 1 - Responsibility - Technology stack - Interfaces ### Component 2 ... ## Data Flow How data moves through the system ## Key Design Decisions ### Decision 1 - Context - Options considered - Decision made - Rationale ## Technology Stack - Frontend: React, TypeScript - Backend: Python, FastAPI - Database: PostgreSQL - Infrastructure: AWS, Docker, Kubernetes ## Scalability How the system scales ## Security Authentication, authorization, data protection ## Monitoring and Observability Metrics, logs, tracing ## Disaster Recovery Backup and recovery procedures ## Future Considerations Runbook: # [Service Name] Runbook ## Service Overview What this service does ## Dependencies - Service A - Service B - Database X ## Deployment ### How to deploy ```bash ./deploy.sh production Rollback ./rollback.sh Monitoring Key Metrics Request rate Error rate Latency Dashboards Production Dashboard Alerts Common Issues Issue 1: High latency Symptoms: Response time > 1s Diagnosis: Check database connection pool Resolution: Restart service or scale up Issue 2: Memory leak Symptoms: Memory usage growing over time Diagnosis: Check heap dump Resolution: Restart service, investigate in staging Troubleshooting How to check logs kubectl logs -f deployment/service-name How to access metrics curl https://api/metrics Emergency Contacts On-call: PagerDuty Team Slack: #team-name **API Documentation**: ```markdown # API Documentation ## Authentication All requests require authentication: ```bash curl -H "Authorization: Bearer YOUR_TOKEN" \ https://api.example.com/endpoint Endpoints List Users GET /api/v1/users Parameters: Name Type Required Description page integer No Page number (default: 1) limit integer No Items per page (default: 20) Example Request: curl -X GET "https://api.example.com/api/v1/users?page=1&limit=20" \ -H "Authorization: Bearer YOUR_TOKEN" Example Response: { "data": [ { "id": 1, "name": "John Doe", "email": "john@example.com" } ], "pagination": { "page": 1, "limit": 20, "total": 100 } } Error Responses: Status Description 400 Bad Request 401 Unauthorized 500 Server Error ### Step 3: Writing guidelines **Clarity**: - Use simple, direct language - One idea per sentence - Short paragraphs (3-5 sentences) - Define technical terms - Avoid jargon when possible **Structure**: - Use hierarchical headings (H1, H2, H3) - Break content into sections - Use lists for multiple items - Use tables for structured data - Add table of contents for long docs **Examples**: - Include code examples - Provide diagrams - Show before/after comparisons - Real-world scenarios **Completeness**: - Cover prerequisites - Include error handling - Document edge cases - Explain why, not just how - Link to related docs **Consistency**: - Consistent terminology - Consistent formatting - Consistent code style - Consistent structure ### Step 4: Visual aids **Architecture diagrams** (Mermaid): ```mermaid graph TB A[Client] -->|HTTP| B[Load Balancer] B --> C[Web Server 1] B --> D[Web Server 2] C --> E[Database] D --> E Sequence diagrams: sequenceDiagram Client->>+Server: Request Server->>+Database: Query Database-->>-Server: Data Server-->>-Client: Response Flowcharts: flowchart TD A[Start] --> B{Is valid?} B -->|Yes| C[Process] B -->|No| D[Error] C --> E[End] D --> E Code blocks with syntax highlighting: def calculate_total(items: List[Item]) -> Decimal: """Calculate total price of items.""" return sum(item.price for item in items) Screenshots: Use for UI documentation Annotate important parts Keep up-to-date with UI changes Tables: Parameter Type Default Description timeout int 30 Request timeout in seconds retries int 3 Number of retry attempts Step 5: Review and refine Self-review checklist: Clear purpose stated upfront Logical flow of information All terms defined Code examples tested Links work Diagrams are clear No typos or grammar errors Consistent formatting Table of contents (if needed) Last updated date Get feedback: Have someone from target audience review Test instructions (can they follow them?) Check for missing information Verify accuracy Maintain documentation: Update with code changes Version your docs Archive outdated docs Regular review cycle Document templates Technical Spec Template # [Feature Name] Technical Spec **Author**: [Your Name] **Date**: [Date] **Status**: [Draft/Review/Approved] ## Overview [1-2 paragraphs describing what this document covers] ## Background [Context and motivation] ## Goals - Goal 1 - Goal 2 ## Non-Goals - What we're not doing ## Detailed Design [Technical details] ## Alternatives Considered [Other approaches and why we didn't choose them] ## Timeline - Week 1: ... - Week 2: ... ## Open Questions - Question 1 - Question 2 ## Features - Feature 1 - Feature 2 ## Installation ### Prerequisites - Node.js >= 14 - npm >= 6 ### Setup ```bash git clone https://github.com/user/project.git cd project npm install Usage npm start Configuration Environment variables: API_KEY: Your API key PORT: Server port (default: 3000) Development npm run dev npm test Deployment [Deployment instructions] Contributing [Contributing guidelines] License MIT ### Changelog Template ```markdown # Changelog ## [1.2.0] - 2024-01-15 ### Added - New feature X - Support for Y ### Changed - Improved performance of Z - Updated dependency A to v2.0 ### Fixed - Bug where user couldn't login - Memory leak in background task ### Deprecated - Old API endpoint /v1/users (use /v2/users) ### Removed - Legacy authentication method ### Security - Fixed XSS vulnerability in comments ## [1.1.0] - 2024-01-01 ... Writing tips Use active voice ✅ Good: "The system sends a notification" ❌ Bad: "A notification is sent by the system" Be concise ✅ Good: "Click Save to save changes" ❌ Bad: "In order to save your changes, you should click on the Save button" Use examples ✅ Good: "Set the timeout in seconds: ```yaml timeout: 30 ❌ Bad: "Configure the timeout parameter appropriately" ### Break down complexity ✅ Good: "To deploy: Build the image Push to registry Update deployment Verify rollout" ❌ Bad: "Deploy by building and pushing the image to the registry, then update the deployment and verify the rollout succeeded" ## Common mistakes to avoid 1. **Assuming knowledge**: Define terms, explain context 2. **Outdated docs**: Keep in sync with code 3. **Missing examples**: Always include examples 4. **No visuals**: Use diagrams for complex concepts 5. **Poor structure**: Use headings and sections 6. **Passive voice**: Use active voice 7. **Too much jargon**: Write for your audience 8. **No version info**: Date docs, note versions 9. **Missing error cases**: Document what can go wrong 10. **No maintenance**: Update regularly ## Best practices 1. **Write for your audience**: Match their knowledge level 2. **Start with why**: Explain the purpose 3. **Show, don't just tell**: Use examples 4. **Be consistent**: Terminology, style, structure 5. **Test your docs**: Can someone follow them? 6. **Version your docs**: Track with code versions 7. **Use templates**: Consistency across docs 8. **Link related docs**: Help readers find more info 9. **Update with code**: Docs are part of the code 10. **Review regularly**: Quarterly doc review ## Tools **Diagram tools**: - Mermaid (markdown-based) - Draw.io - Lucidchart - PlantUML **Documentation platforms**: - GitBook - Docusaurus - MkDocs - Sphinx **Style checkers**: - Grammarly - Hemingway Editor - Vale **Screenshot tools**: - Snagit - CloudApp - Loom (for videos) ## Examples ### Example 1: Basic usage ### Example 2: Advanced usage Weekly Installs11.1KRepositorysupercent-io/sk…templateGitHub Stars53First SeenJan 24, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled oncodex11.0Kgemini-cli11.0Kopencode11.0Kgithub-copilot10.9Kcursor10.9Kamp10.9K --- *Source: https://skills.yangsir.net/skill/sm-technical-writing* *Markdown mirror: https://skills.yangsir.net/api/skill/sm-technical-writing/markdown*