technical-writing

# Technical Writing

Write clear, consistent technical documentation based on Google's developer
documentation style guide.

## Core Principles

- **Clarity over cleverness**: Prioritize understandable prose over elegant
  writing
- **Consistency matters**: Apply rules uniformly throughout a document
- **Audience-first**: Write for developers with varying English proficiency

## Voice and Tone

**Use second person**: Address the reader directly with "you."

Good: "You can configure the server by editing `config.yaml`."
Bad: "We can configure the server by editing `config.yaml`."

**Use active voice**: Make clear who performs the action.

Good: "The function returns an error code."
Bad: "An error code is returned by the function."

**Be conversational but professional**: Write naturally without slang, jargon,
or excessive formality. Use common contractions like "you're," "don't," and
"it's" to maintain an informal tone.

## What to Avoid

- **Jargon and buzzwords**: "leverage," "utilize," "synergy"
- **Filler phrases**: "please note that," "it should be noted"
- **Exclamation marks**: Reserve for genuinely exciting moments
- **Implying simplicity**: "simply," "just," "easy" (frustrates struggling
  readers)
- **Latin abbreviations**: Write "for example" not "e.g.", "that is" not "i.e."
- **Directional language**: Use "earlier/later" not "above/below"
- **Anthropomorphic language**: Don't attribute human qualities to software
  ("the system wants," "the server thinks")
- **Skipping articles**: Always include "a," "an," and "the"—even in headings

## Inclusive Language

| Avoid               | Use Instead                            |
| ------------------- | -------------------------------------- |
| blacklist/whitelist | denylist/allowlist, blocklist/safelist |
| master/slave        | primary/replica, leader/follower       |
| man-hours           | person-hours                           |
| guys                | everyone, folks, team                  |
| sanity check