Technical Writing

<!-- Bad: assumes context, branches, explains -->
Depending on your package manager, install the SDK (we use a monorepo
because it scales better). Configure your environment as needed.

<!-- Good: one path, concrete, checkable -->
## Build your first report

You need Python 3.12+ and a free API key from example.com/keys.

1. Install the SDK:
   ```bash
   pip install acme-sdk==4.2.0

## How-to

A recipe for someone who already knows the product and has a real goal right now.

- Title it as the goal: **"How to rotate an API key"**, not "API keys".
- Assume competence. Do not re-teach concepts; link to reference/explanation instead.
- Ordered steps, but the reader may adapt — state the goal so they can.
- Address one real-world task. "How to configure logging" is reference; "How to ship logs to Datadog" is a how-to.
- No tutorial hand-holding, no narrative.

Bad → Good:

```md
<!-- Bad: teaches, no clear goal in the title -->
## Logging
Logging is important. A logger has levels: DEBUG, INFO… Here is how
levels work, and then some setup.

<!-- Good: goal title, competent reader, straight to it -->
## How to send logs to Datadog
1. Set `LOG_SINK=datadog` and `DD_API_KEY` in the environment.
2. Restart the worker: `acme worker restart`.
3. Confirm delivery in Datadog → Logs within ~1 min.

### `GET /reports/{id}`

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes | Report identifier. |
| `fields` | query | string | no | Comma-separated fields to return. Default: all. |

**Responses**

| Status | Meaning |
|---|---|
| `200` | Report returned. |
| `404` | No report with that `id`. |
| `429` | Rate limit exceeded; retry after `Retry-After` seconds. |

<!-- Bad: a sales page -->
# Acme SDK 🚀
The most powerful, blazing-fast, developer-friendly toolkit to
effortlessly supercharge your data workflows!

<!-- Good: what it is, what it's for, in two lines -->
# Acme SDK
A Python client for the Acme reporting API. Fetch, filter, and export
reports without writing HTTP by hand.

## Install
```bash
pip install acme-sdk==4.2.0

## Sentence-level rules

Apply these to every mode. Each ships clearer prose at no cost.

| Rule | Why | Bad → Good |
|---|---|---|
| Second person, imperative steps | The reader is *doing* this | "The user should run…" → "Run…" |
| Active voice | Names who acts | "The file is created by the script" → "The script creates the file" |
| Present tense | Docs describe how it works now | "This will return a list" → "This returns a list" |
| Define before use | No forward references | Spell out a term the first time, then use it |
| One idea per sentence | Scannable, translatable | Split the 40-word sentence into two |
| Cut "in order to" | It is always just "to" | "in order to deploy" → "to deploy" |
| Ban weasel/AI-tell words | They lie about difficulty and add nothing | "simply run X" → "run X" |

Banned words: **simply, just, easy, effortless, seamless, robust, powerful, leverage, utilize, in order to, blazing-fast, supercharge**. If a step is "simple", the reader either already knows it (delete the word) or does not (the word mocks them). Full banlist with replacements is in `references/diataxis-modes.md`.

## Code examples

- Minimal: the fewest lines that work. Cut every line not required to run.
- Runnable and **tested** — copy-paste it onto a clean machine and confirm. Untested samples rot and misinform.
- Language-tag every fence (`bash`, `python`, `json`, `yaml`, `ini`).
- Show expected output so the reader knows they succeeded.
- No `...` standing in for required lines. Elide only genuinely irrelevant detail, and say so.

```python
# Good: minimal, runnable, shows what comes back
from acme import Client

client = Client(api_key="your-key")
report = client.reports.get("3f9a-...")
print(report.title)
# -> "Q2 revenue"