Reference, ADRs, changelogs: milestone 2

Diátaxis is strict here, and the strictness is the value. Reference is austere and factual technical description. Its structure mirrors the structure of the thing it describes: the reference for config.yaml is organized like config.yaml, not like a lesson plan. And it never gives instructions.

• Describe, don't teach. "clean.py drops rows whose event type is not in this list" is reference. "You should keep this list small" is opinion; "to add a type, edit the list and rerun" is a how-to. Both leak into reference pages constantly, and both belong elsewhere.
• "How to change it" is a link, not a paragraph. When the maintainer reading about alerts.min_daily_events wants to tune it, the reference links to a how-to. Mixing instruction into description makes the page longer to scan and harder to trust - is this line a fact or a suggestion?
• Examples are allowed; instruction is not. Diátaxis explicitly permits illustrative examples in reference ("a valid value looks like page_view"). The line it draws is between showing what something is and telling the reader what to do.

Diátaxis: reference should follow standard patterns, the way a dictionary gives every word the same treatment. For a config reference, that means every key gets the same fields, in the same order, every time:

• Type - what kind of value this is (path, integer, list of strings).
• Default - the value that ships, exactly as it appears in the file.
• Effect - what the pipeline does with it, in one factual sentence.
• Safe range - what values work, and what breaks outside them.

The payoff is mechanical: after the first entry, the reader's eyes know where the default lives on the page. They stop reading and start looking up - which is the entire job of a reference page. It also makes gaps visible: an entry missing its "safe range" line is obviously unfinished, in a way a free-prose paragraph never is.

Today Pulse's reference fits on one page. Google's Technical Writing Two covers what to do when it doesn't - when a doc grows enough that readers get lost inside it:

• Split by reader task, not by module. The signal to break one doc into several is that different readers come for different jobs. Outline first; a doc that resists outlining is usually two docs.
• Introductions declare coverage. Each resulting doc opens by stating what it covers, what it assumes, and what it deliberately excludes - the Session 1 declarations, applied at scale.
• Task-based headings, text under every heading. "Configuring alerts" beats "Alerts"; and never jump from a heading straight to a subheading - give the reader at least a sentence of orientation first.
• Progressive disclosure, simple to complex. Early sections must not depend on late ones. The common case comes first; the exotic override lives at the bottom, where only the reader who needs it will ever scroll.

Nygard's template has five short sections, written in full sentences - he describes an ADR as a conversation with a future developer, one or two pages long. Pulse has a perfect first candidate: clean.py silently converts every timestamp to UTC, a decision that once caused real pain and that no doc currently explains. Here is the template, with ADR-001 as the worked example:

The consequences section is where most ADRs go wrong. If yours lists only benefits, it isn't a record of a decision - it's a press release. The negative consequences are precisely what the future developer needs: "naive non-UTC sources are silently mis-read" is the sentence that saves them a week of debugging.

Keep a Changelog (v1.1.0) starts from one principle: changelogs are for humans, not machines. A human is deciding whether to upgrade, what to test, what might break. Everything else follows:

• One entry per version, newest first, with an ISO 8601 date (2026-07-14, never 07/14/26 - a date format half the world reads backwards is not for humans).
• Group changes into six categories: Added, Changed, Deprecated, Removed, Fixed, Security. The categories do the reader's triage for them - Security and Removed get read first, every time.
• Keep an [Unreleased] section at the top. Merged-but-unshipped changes accumulate there, so cutting a release is a rename, not an afternoon of git spelunking.
• Say whether you follow SemVer. One line at the top; it tells readers how to interpret your version numbers.

And the anti-patterns, which keepachangelog calls out by name: dumping your commit log (commits are for machines; "refactor helpers, fix typo, wip" tells an upgrader nothing), ignoring deprecations (the reader's one chance to migrate calmly), regional date formats, and selective reporting - a changelog that hides the embarrassing changes trains readers to distrust all of it.

Conventions from adr.github.io and Nygard's original post, for when Pulse has more than one decision on record:

• ADRs live in the repo (conventionally docs/adr/), versioned with the code they explain. A decision record on a wiki drifts; one in the repo travels with every clone.
• Numbered sequentially, and numbers are never reused. ADR-001 is ADR-001 forever, even if the decision dies.
• Superseded, never deleted. When a decision is reversed, the old ADR's status becomes "superseded by ADR-00X" and it stays put. The trail of reversals is itself the documentation: it tells the future developer this problem is hard and has been solved twice already.
• Keep them 1-2 pages of full sentences. Bullet-point fragments lose the reasoning; the reasoning is the entire point.