frankxai Technical Writing Mastery
"The best documentation is invisible. Users find what they need, understand it immediately, and get back to work."
The Technical Writing Philosophy
DOCUMENTATION IS NOT:
✗ Proof that you built something
✗ A formality to check off
✗ Something to write after shipping
DOCUMENTATION IS:
✓ Part of the product
✓ User experience in text form
✓ Force multiplier for adoption
✓ Investment that pays dividends
The Four Types of Documentation
╔═══════════════════════════════════════════════════════════════════╗
║ DOCUMENTATION TYPES ║
║ (Each serves different needs) ║
╠═══════════════════════════════════════════════════════════════════╣
║ ║
║ TUTORIALS │ Learning-oriented │ "Let me show you" ║
║ HOW-TO GUIDES │ Problem-oriented │ "How to do X" ║
║ REFERENCE │ Information-oriented │ "Technical specs" ║
║ EXPLANATION │ Understanding-oriented│ "Why it works" ║
║ ║
╚═══════════════════════════════════════════════════════════════════╝
Tutorials (Learning)
PURPOSE: Teach newcomers through doing
STRUCTURE: Step-by-step journey
OUTCOME: User completes something real
CHARACTERISTICS:
• Hand-holding is appropriate
• Focus on accomplishment, not completeness
• Explain the "why" as you go
• End with something that works
How-To Guides (Problem Solving)
PURPOSE: Help users accomplish specific tasks
STRUCTURE: Step-by-step instructions
OUTCOME: User solves their problem
CHARACTERISTICS:
• Assumes basic knowledge
• Focused on single goal
• Practical, not educational
• Skips unnecessary context
Reference (Information)
PURPOSE: Describe the machinery
STRUCTURE: Systematic, complete
OUTCOME: User finds technical details
CHARACTERISTICS:
• Consistent format
• Complete and accurate
• No tutorial content
• Code examples for each item
Explanation (Understanding)
PURPOSE: Clarify and illuminate
STRUCTURE: Discursive, connecting
OUTCOME: User understands deeply
CHARACTERISTICS:
• Discusses alternatives
• Explains reasoning
• Provides context
• Answers "why?"
Writing Principles
Clarity Over Cleverness
BAD: "Leverage the paradigm-shifting capabilities..."
GOOD: "Use X to do Y."
BAD: "The system utilizes..."
GOOD: "The system uses..."
BAD: "It should be noted that..."
GOOD: Just say the thing.
Active Voice
PASSIVE: "The file is created by the system."
ACTIVE: "The system creates the file."
PASSIVE: "The configuration should be updated."
ACTIVE: "Update the configuration."
Present Tense
PAST: "This function returned..."
PRESENT: "This function returns..."
FUTURE: "This will create..."
PRESENT: "This creates..."
Direct Address
IMPERSONAL: "One might want to..."
DIRECT: "You might want to..."
IMPERSONAL: "The user should..."
DIRECT: "You should..."
Structure Patterns
The README Template
# Project Name
One-sentence description of what this does.
## Quick Start
The absolute minimum to get running.
## Installation
```bash
npm install project-name
Basic Usage
import { thing } from 'project-name';
thing.doSomething();
API Reference
Link to full docs.
Contributing
How to contribute.
License
MIT (or whatever)
### The API Reference Template
```markdown
## functionName(param1, param2)
Brief description of what it does.
### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | What this is |
| param2 | number | No | What this is |
### Returns
`Type` - Description of return value
### Example
```javascript
const result = functionName('hello', 42);
console.log(result); // Expected output
Errors
| Error | When |
|---|---|
| InvalidParam | When param1 is empty |
### The Tutorial Template
```markdown
# Tutorial: [What You'll Build]
By the end of this tutorial, you will have [concrete outcome].
## Prerequisites
- What you need to know
- What you need installed
## Step 1: [First Action]
Brief explanation of what we're doing and why.
```code
Actual code to run
You should see [expected result].
Step 2: [Next Action]
[Continue pattern...]
What You've Learned
- Point 1
- Point 2
Next Steps
Where to go from here.
---
## Common Mistakes
### Mistake: Assuming Knowledge
BAD: "Configure the webhook endpoint."
GOOD: "Configure the webhook endpoint. Webhooks are HTTP callbacks that notify your server when events occur. To set one up..."
### Mistake: Missing Examples
BAD: "The format parameter accepts a string."
GOOD: "The format parameter accepts a string.
Example:
const result = format('date', 'YYYY-MM-DD');
// Returns: '2024-01-15'
```"
Mistake: Outdated Code
BAD:
Code examples that don't work with current version.
GOOD:
Version-tagged examples that are tested in CI.
Mistake: Wall of Text
BAD:
Long paragraphs with no visual breaks.
GOOD:
• Short paragraphs
• Bullet points
• Code blocks
• Headers for scanning
Maintenance
Keep Docs Current
□ Docs updated with every feature change
□ Code examples tested automatically
□ Broken link checks automated
□ Version numbers accurate
□ Deprecation notices added
Gather Feedback
• Track which pages have high bounce rates
• Monitor support questions (they reveal gaps)
• Include "Was this helpful?" feedback
• Watch for confusion patterns
Quick Reference
Writing Checklist
□ Used active voice
□ Used present tense
□ Addressed reader directly ("you")
□ Included working code examples
□ Tested all code examples
□ Added error handling examples
□ Linked to related topics
□ Formatted for scanning
□ Reviewed for accuracy
Tone Guidelines
BE:
• Friendly but professional
• Confident but not arrogant
• Concise but complete
• Helpful but not patronizing
AVOID:
• Jargon without explanation
• Humor that might not translate
• Assumptions about user knowledge
• Passive-aggressive language
"Documentation is a love letter to your future users. Write it with care."