technical-writing

What this skill does

# 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

## Clear and Concise Writing Techniques

### Sentence Construction
- **Short Sentences**: Aim for 15-20 words per sentence
- **Simple Words**: Use familiar words over complex ones
- **Active Verbs**: Choose strong, specific verbs
- **Subject-Verb-Object**: Use SVO order for clarity
- **Avoid Nominalization**: Turn nouns back into verbs

### Paragraph Structure
- **Topic Sentences**: Start each paragraph with the main idea
- **One Idea per Paragraph**: Keep paragraphs focused
- **Transitional Phrases**: Use transitions to connect ideas
- **Short Paragraphs**: Aim for 3-5 sentences per paragraph
- **White Space**: Use white space to improve readability

## Diagram and Visual Content Creation

### Types of Diagrams
- **Flowcharts**: Show processes and decision points
- **Sequence Diagrams**: Illustrate interactions between components
- **Architecture Diagrams**: Depict system structure and relationships
- **Entity Relationship Diagrams**: Show data relationships
- **State Diagrams**: Represent system states and transitions

### Visual Best Practices
- **Keep It Simple**: Avoid clutter and unnecessary details
- **Use Consistent Style**: Maintain visual consistency across diagrams
- **Label Clearly**: Use clear, descriptive labels
- **Color Coding**: Use color purposefully to convey meaning
- **Include Legends**: Explain symbols and color meanings
- **Alt Text**: Provide alternative text for accessibility