clear-writing

# Clear Writing

Write with clarity and force. This skill covers what to do (Strunk's rules), how to structure technical documentation (Divio patterns, templates), and what not to do (AI anti-patterns, doc anti-patterns).

## When to Use

Use this skill whenever you write prose for humans:

- Documentation, README files, technical explanations
- API documentation, endpoint references, integration guides
- Tutorials, how-to guides, architecture docs
- Commit messages, pull request descriptions
- Error messages, UI copy, help text, comments
- Reports, summaries, or any explanation
- Editing existing prose to improve clarity

**If you're writing sentences for a human to read, use this skill.**

## Limited Context Strategy

When context is tight:

1. Write your draft using judgment
2. Dispatch a subagent with your draft and the relevant reference file
3. Have the subagent copyedit and return the revision

Loading a single reference (~1,000–4,500 tokens) instead of the full skill saves significant context.

## Elements of Style

William Strunk Jr.'s *The Elements of Style* (1918) teaches you to write clearly and cut ruthlessly.

### Rules

**Elementary Rules of Usage (Grammar/Punctuation)**:

1. Form possessive singular by adding 's
2. Use comma after each term in series except last
3. Enclose parenthetic expressions between commas
4. Comma before conjunction introducing co-ordinate clause
5. Don't join independent clauses by comma
6. Don't break sentences in two
7. Participial phrase at beginning refers to grammatical subject

**Elementary Principles of Composition**:

8. One paragraph per topic
9. Begin paragraph with topic sentence
10. **Use active voice**
11. **Put statements in positive form**
12. **Use definite, specific, concrete language**
13. **Omit needless words**
14. Avoid succession of loose sentences
15. Express co-ordinate ideas in similar form
16. **Keep related words together**
17. Keep to one tense in summaries
18. **Place emphatic words at end of sentence**

### Reference Files

For complete explanations with examples:

| Section | File | ~Tokens |
|---------|------|---------|
| Grammar, punctuation, comma rules | `references/elements-of-style/02-elementary-rules-of-usage.md` | 2,500 |
| Paragraph structure, active voice, concision | `references/elements-of-style/03-elementary-principles-of-composition.md` | 4,500 |
| Headings, quotations, formatting | `references/elements-of-style/04-a-few-matters-of-form.md` | 1,000 |
| Word choice, common errors | `references/elements-of-style/05-words-and-expressions-commonly-misused.md` | 4,000 |

**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete language, and omitting needless words.

## AI Writing Patterns to Avoid

LLMs regress to statistical means, producing generic, puffy prose. Avoid:

- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word

Be specific, not grandiose. Say what it actually does.

For comprehensive research on why these patterns occur, see `references/signs-of-ai-writing.md`. Wikipedia editors developed this guide to detect AI-generated submissions — their patterns are well-documented and field-tested.

## Document Types (Divio Framework)

| Type | Purpose | Structure |
|------|---------|-----------|
| README | First impression, project overview | Title, description, quick start, install, usage |
| Tutorial | Learning-oriented, guided experience | Numbered steps with expected outcomes |
| How-to Guide | Task-oriented, solve a specific problem | Problem statement → steps → result |
| Reference | Information-oriented, complete and accurate | Alphabetical or grouped, consistent format |
| Explanation | Understanding-oriented, context and rationale | Narrative prose, diagrams, history |
| Architecture Doc | System design, component relationships | Context → components → data flow → decisions |
| API Documentation | Endpoint contracts, integration guide | Endpoint → params → request → response → errors |

## Structure Patterns

### Inverted Pyramid

Lead with the most important information. Each subsequent section adds detail.

```
1. What it does (one sentence)
2. How to use it (quick start)
3. Configuration options
4. Advanced usage
5. Internals / implementation details
```

### Problem-Solution

```
1. Problem — what goes wrong, symptoms, error messages
2. Cause — why it happens (brief)
3. Solution — step-by-step fix
4. Prevention — how to avoid it in the future
```

### Sequential Steps

Every step is a single action with a verifiable outcome.

```
1. Step — one action, one verb
   Expected result: what the reader should see
2. Step — next action
   Expected result: confirmation of success
```

## Writing Rules

| Rule | Guideline | Example |
|------|-----------|---------|
| Short sentences | Keep under 25 words | "The server restarts automatically after config changes." |
| Active voice | Subject does the action | "The function returns a promise" not "A promise is returned" |
| Present tense | Describe current behavior | "This endpoint accepts JSON" not "will accept JSON" |
| One idea per paragraph | Each paragraph has one point | Split compound paragraphs at the topic shift |
| Define jargon on first use | Never assume vocabulary | "The ORM (Object-Relational Mapper) translates..." |
| Second person | Address the reader directly | "You can configure..." not "One can configure..." |
| Consistent terminology | Pick one term and stick with it | Don't alternate between "repo" and "repository" |
| Concrete over abstract | Specifics beat generalities | "Returns a 404 status code" not "Returns an error" |

## Code Examples in Documentation

Every code example must follow these rules:

1. **Complete and runnable** — copy-paste and execute without modification
2. **Annotated** — comments on the non-obvious parts, not the obvious ones
3. **Progressive complexity** — simplest case first, then advanced usage
4. **Language-tagged** — always specify the language in fenced code blocks
5. **Current** — examples must work with the documented version
6. **Minimal** — show only what is relevant; strip unrelated boilerplate

```python
# Good: complete, annotated, minimal
import httpx

# Create a client with a base URL to avoid repeating it
client = httpx.Client(base_url="https://api.example.com")

# Fetch a user by ID — returns a User dict or raises for 4xx/5xx
response = client.get("/users/42")
response.raise_for_status()
user = response.json()
print(user["name"])  # "Ada Lovelace"
```

## README Template

```markdown
# Project Name

One-line description of what this project does and who it is for.

## Quick Start

The fastest path from zero to working. Three commands or fewer.

## Installation

Prerequisites, system requirements, and step-by-step install.

## Usage

Common use cases with code examples. Cover the 80% case.

## API

Public API surface — functions, classes, CLI flags, endpoints.

## Configuration

Environment variables, config files, and their defaults.

## Contributing

How to set up the dev environment, run tests, and submit changes.

## License

License name and link to the full LICENSE file.
```

**README rules:**

- Keep the quick start under 60 seconds of reader time
- Include a badge row only if badges are kept current
- Link to deeper docs rather than bloating the README
- Update the README whenever the public interface changes

## API Documentation Pattern

Document every endpoint with this structure:

```markdown
### GET /users/:id

Retrieve a single user by their unique identifier.

**Authentication:** Bearer token required

**Path Parameters:**

| Parameter | Type   | Required | Description          |
|-----------|--------|----------|----------------------|
| id        | string | Yes      | The user's unique ID |

**Response: 200 OK**

{json response example}

**Error Responses:**

| Status | Code         | Description              |
|--------|--------------|--------------------------|
| 401    | UNAUTHORIZED | Missing or invalid token |
| 404    | NOT_FOUND    | User does not exist      |
```

Always document errors with: HTTP status, machine-readable error code, human-readable message, and resolution steps.

## Audience Adaptation

| Audience | Context Level | Focus | Tone |
|----------|--------------|-------|------|
| Beginner | High — define terms, explain prerequisites | What and how, step by step | Encouraging, patient |
| Intermediate | Medium — assume basic knowledge | How and best practices | Direct, practical |
| Expert | Low — skip fundamentals | Why, edge cases, tradeoffs | Concise, precise |

**Rules:**

- State the assumed audience at the top of the document
- Link to prerequisite knowledge rather than re-explaining it
- Use expandable sections (`<details>`) for beginner context in expert docs
- Never mix audience levels in the same section

## Review Checklist

Before publishing any documentation:

- [ ] **Accurate** — all code examples run, all commands work, all links resolve
- [ ] **Complete** — covers setup, happy path, error cases, and cleanup
- [ ] **Consistent** — terminology, formatting, and voice match the rest of the docs
- [ ] **Readable** — passes a cold read by someone unfamiliar with the project
- [ ] **Scannable** — headings, tables, and lists allow skimming for answers
- [ ] **Examples work** — every code block tested against the current version
- [ ] **Links valid** — no broken internal or external links
- [ ] **Audience-appropriate** — context level matches the stated audience
- [ ] **Up to date** — no references to deprecated features or old versions
- [ ] **Spellchecked** — no typos, no inconsistent capitalization

## Documentation Anti-Patterns

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Wall of text | Readers bounce | Break into sections with headings and lists |
| Outdated docs | Erodes trust | Tie doc updates to PR checklists; date-stamp pages |
| No examples | Readers can't apply abstract descriptions | Add code examples for every public function |
| Assumed knowledge | Excludes beginners | Define terms on first use, link to prerequisites |
| Copy-paste unfriendly | Code with `$` prompts or line numbers breaks when pasted | Provide clean, runnable code blocks |
| Screenshot-only instructions | Can't be searched, go stale, inaccessible | Pair screenshots with text and commands |

## NEVER Do

1. **NEVER publish docs without testing every code example** — broken examples destroy credibility faster than anything else
2. **NEVER write docs after the fact as an afterthought** — write docs alongside the code; if you cannot explain it, the design needs work
3. **NEVER use "simply", "just", or "obviously"** — these words shame readers who are struggling and add no information
4. **NEVER mix multiple audiences in one document** — write separate beginner and advanced guides, or use clear section boundaries
5. **NEVER leave placeholder text in published docs** — "TODO", "TBD", and "lorem ipsum" signal abandonment
6. **NEVER duplicate content across documents** — link to a single source of truth; duplicates inevitably drift apart
7. **NEVER omit the date or version** — readers must know if they are looking at current information
8. **NEVER use AI puffery words** — pivotal, crucial, seamless, robust, groundbreaking, tapestry, and their ilk add nothing and signal lazy writing