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