arcanea-technical-writing

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

### 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."