technical-writing

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: technical-writing
description: Technical writing principles and best practices for creating clear, accurate documentation
---

# Technical Writing

## Technical Writing Principles

### Clarity
- **Use Simple Language**: Write at an 8th-grade reading level for general audiences
- **Avoid Jargon**: Define technical terms or use simpler alternatives
- **Be Concise**: Remove unnecessary words and filler content
- **Use Active Voice**: Active voice is clearer and more direct than passive voice
- **One Idea per Sentence**: Keep sentences focused and easy to understand

### Accuracy
- **Verify Facts**: Double-check all technical information, code examples, and data
- **Test Instructions**: Follow documented steps to ensure they work
- **Cite Sources**: Attribute information to reliable sources
- **Update Regularly**: Keep documentation current with software changes
- **Peer Review**: Have subject matter experts review technical content

### Completeness
- **Cover All Steps**: Include every step needed to complete a task
- **Address Edge Cases**: Document what happens in unusual scenarios
- **Include Prerequisites**: List all required knowledge, tools, and setup
- **Provide Context**: Explain why something matters, not just how to do it
- **Add Troubleshooting**: Anticipate and address common problems

## Documentation Style Guides

### Google Developer Documentation Style Guide
- **Tone**: Friendly, clear, and direct
- **Voice**: Second person ("you") for instructions
- **Tense**: Present tense for general information, imperative for instructions
- **Formatting**: Use sentence case for headings, title case for page titles
- **Code**: Use code blocks with syntax highlighting, monospace for inline code

### Microsoft Style Guide
- **Tone**: Professional, clear, and consistent
- **Voice**: Active voice, direct address to reader
- **Tense**: Present tense for concepts, imperative for procedures
- **Formatting**: Use sentence case for UI elements, title case for headings
- **Terminology**: Use Microsoft-specific terminology consistently

## Writing for Different Audiences

### Developers
- **Assume Technical Knowledge**: Developers understand programming concepts
- **Focus on Code**: Provide code examples, API references, and implementation details
- **Include Architecture**: Explain system design and technical decisions
- **Use Technical Terminology**: Use industry-standard terms without over-explaining
- **Provide Best Practices**: Share patterns, conventions, and optimization tips

### End Users
- **Assume Minimal Technical Knowledge**: Explain concepts in simple terms
- **Focus on Tasks**: Provide step-by-step instructions for common tasks
- **Include Screenshots**: Visual aids help non-technical users
- **Avoid Code**: Minimize or explain code examples
- **Provide Context**: Explain why actions are needed, not just how to do them

### Stakeholders
- **Focus on Value**: Explain benefits and business impact
- **Use Business Language**: Avoid technical jargon, use business terms
- **Provide Summaries**: Include executive summaries and key takeaways
- **Include Metrics**: Use data and metrics to support claims
- **Address Concerns**: Anticipate and address stakeholder questions

## Structuring Technical Content

### Information Architecture
- **Hierarchical Structure**: Organize content from general to specific
- **Logical Flow**: Arrange topics in a logical, user-centered order
- **Chunking**: Break long content into manageable sections
- **Progressive Disclosure**: Reveal information as needed
- **Cross-References**: Link related content for comprehensive coverage

### Document Structure
- **Title**: Clear, descriptive, and searchable
- **Introduction**: Overview of what the document covers
- **Prerequisites**: Required knowledge, tools, and setup
- **Body**: Main content organized with headings and subheadings
- **Conclusion**: Summary and next steps
- **Appendices**: Additional information, references, and glossaries

## Cl