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