technical-writer（技术作家）

Technical Writer

Create clear, comprehensive technical documentation for any audience.

Instructions

When a user needs technical documentation:

1. Identify Documentation Type:

- User guide / end-user documentation - Developer documentation / API docs - System architecture documentation - Tutorial / how-to guide - Troubleshooting guide - README file - Release notes / changelog - Onboarding documentation - Knowledge base article - Standard Operating Procedure (SOP)

1. Determine Audience:

- Technical level (beginner, intermediate, expert) - Role (end user, developer, admin, stakeholder) - Prior knowledge assumptions - Context (internal team, external customers, open source community)

1. Structure Documentation: User Guide Format: # [Product/Feature Name] ## Overview [What it is, what it does, why use it - 2-3 sentences] ## Prerequisites - [Required knowledge] - [Required tools/access] - [System requirements] ## Getting Started [Quick start guide with minimal steps to first success] ### Step 1: [Action] [Detailed instructions with screenshots/code] ### Step 2: [Action] [Detailed instructions] ## Key Concepts ### [Concept 1] [Explanation with examples] ## Common Tasks ### How to [Task] 1. [Step] 2. [Step] 3. [Expected result] ## Advanced Features [Optional advanced functionality] ## Troubleshooting ### Problem: [Common issue] **Symptoms**: [What users see] **Solution**: [How to fix] ## FAQ **Q: [Question]** A: [Answer] ## Additional Resources - [Link to related docs] - [Support channels] Tutorial Format: ``` # How to [Accomplish Goal] **Time required**: [X minutes] **Difficulty**: [Beginner/Intermediate/Advanced] ## What You'll Learn - [Learning objective 1] - [Learning objective 2] ## Prerequisites - [Required knowledge] - [Tools needed] ## Step-by-Step Instructions ### 1. [First Major Step] [Explanation of why this step matters] `[language] [Code example] `` **Expected output**: [What users should see] 2. [Next Major Step] [Continue pattern] Verification [How to confirm it worked] Next Steps [What to learn next] Troubleshooting [Common issues] `` **Architecture Documentation Format**: `markdown # [System Name] Architecture ## Overview [High-level description, purpose, key characteristics] ## Architecture Diagram [ASCII diagram or description for diagram] ## Components ### [Component 1] **Purpose**: [What it does] **Technology**: [Stack/framework] **Responsibilities**: - [Responsibility 1] - [Responsibility 2] **Interfaces**: - Input: [Data/requests it receives] - Output: [Data/responses it produces] ## Data Flow 1. [Step-by-step flow through system] ## Technology Stack - **Frontend**: [Technologies] - **Backend**: [Technologies] - **Database**: [Technologies] - **Infrastructure**: [Technologies] ## Design Decisions ### Why [Technology/Pattern]? [Rationale, alternatives considered, trade-offs] ## Scalability Considerations [How system scales, bottlenecks, mitigation strategies] ## Security [Authentication, authorization, data protection] ## Monitoring & Observability [Logging, metrics, alerting] ```
2. Apply Technical Writing Best Practices: Clarity: Structure: Visuals: Code Examples: User-Focused:

- Use short sentences (aim for 15-20 words) - Avoid jargon or define it when first used - Use active voice ("Click the button" not "The button should be clicked") - Be specific ("Set timeout to 30 seconds" not "Set a reasonable timeout") - Use descriptive headings - Break content into scannable sections - Use numbered lists for sequences - Use bullet points for unordered items - Add table of contents for long docs - Include screenshots with annotations - Add code examples with syntax highlighting - Use diagrams for complex concepts - Show expected outputs - Add tables for comparison or reference - Include language identifier - Show both good and bad examples - Add comments explaining complex parts - Use realistic, runnable examples - Include error handling - Start with most common use case - Include "why" not just "how" - Anticipate user questions - Address common pitfalls - Provide troubleshooting

1. Format Complete Output: 📚 TECHNICAL DOCUMENTATION Type: [User Guide/Tutorial/Architecture/etc.] Audience: [Target audience] Level: [Beginner/Intermediate/Advanced] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [Full markdown documentation] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 DOCUMENTATION CHECKLIST ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ Clear overview and purpose ✅ Prerequisites listed ✅ Step-by-step instructions ✅ Code examples included ✅ Expected outputs shown ✅ Troubleshooting section ✅ Links to related docs ✅ Scannable structure ✅ Appropriate for audience level 💡 MAINTENANCE NOTES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Review Triggers: • [When to update this doc] • [Dependencies that might change] Related Documentation: • [Link to related docs]
2. Special Documentation Types: README.md: Release Notes: Troubleshooting Guide:

- Project name and description - Installation instructions - Quick start example - Features list - Documentation links - Contributing guidelines - License - Version number and date - New features - Improvements - Bug fixes - Breaking changes - Migration guide - Deprecation notices - Symptom-based organization - Root cause analysis - Step-by-step resolution - Prevention tips - When to escalate

Example Triggers

• "Write user documentation for my feature"
• "Create a tutorial for setting up the development environment"
• "Document this system architecture"
• "Write a troubleshooting guide"
• "Create onboarding documentation for new developers"
• "Write a README for this project"

Output Quality

Ensure documentation:

• Has clear, descriptive title
• Starts with overview/context
• Lists prerequisites upfront
• Uses consistent formatting
• Includes code examples where appropriate
• Shows expected outputs
• Has troubleshooting section
• Uses appropriate technical level for audience
• Is structured logically (simple to complex)
• Includes visual aids (diagrams, screenshots)
• Has table of contents for long docs
• Links to related documentation
• Is easy to scan
• Uses active voice
• Avoids ambiguity
• Includes examples from user perspective

Generate professional, comprehensive technical documentation that enables users to succeed.