/write-docs

name: write-docs
description: Write documentation that reads like a person wrote it for another person. The skill teaches the craft layer first, how to set context, how to calibrate tone, how to escape the curse of knowledge, when prose beats a bullet list, and only then the structural conventions (Diátaxis modes, README landing-page arc). Use whenever you're writing or restructuring a README, a docs tree, a CONTRIBUTING file, a guide, an architecture document, or any other documentation surface.

Write docs

Most bad documentation is not unclear, ungrammatical, or factually wrong. It is technically correct prose that nobody wants to read, written by someone who already knows the answer for an imagined reader who knows almost as much. The fix is not another style rule. The fix is to write the way a person teaches another person, assuming nothing, leading with the situation the reader is actually in, providing context where it lands rather than where it's tidiest, and resisting the urge to convert every paragraph into a bulleted enumeration.

This skill teaches the craft first and the conventions second. The craft is what makes a docs page feel earned. The conventions just keep you out of the most expensive failure modes.

Four sources do the heavy lifting:

• **[Steven Pinker, *The Sense of Style*](https://www.psychologicalscience.org/observer/the-curse-of-knowledge-pinker-describes-a-key-cause-of-bad-writing)** for *the curse of knowledge* and *classic style*.
• **[Chip & Dan Heath, *Made to Stick*](https://heathbrothers.com/made-to-stick-introduction/)** for *tappers and listeners* (Newton 1990) and concrete-over-abstract diction.
• **[Mailchimp Content Style Guide](https://styleguide.mailchimp.com/voice-and-tone/)** for *voice is consistent, tone shifts*.
• **[Diátaxis](https://diataxis.fr/)** + the celebrated landing pages (React, Stripe, Anthropic, SpacetimeDB, Tokio) for *structural shape*.

When to invoke

Whenever you're writing or restructuring documentation, a README, a docs tree, a CONTRIBUTING file, a guide, an API reference, an architecture document, an FAQ, or release notes (though release notes have their own skill at `/flagrare:release-check`). Invoke proactively after implementing a feature whose docs need to land alongside the code, or when a staleness audit surfaces documentation drift as the blocker.

This skill does **not** handle changelogs or release notes themselves, `/flagrare:release-check` owns those with its own voice (Valve Dota patch notes).

The procedure

1. Start with the reader's situation, not the page's topic

The single most useful question to ask before writing the first sentence is: *what just happened to the reader, that they ended up on this page?* They Googled an error message. They followed a link from a tutorial. They're three months into using your library and just hit an edge case. They're a new team member reading the docs because their manager said to.

The reader's situation is the context you have to honor. Pinker calls the failure to do this **the curse of knowledge**: "a difficulty in imagining what it is like for someone else not to know something that you know." The Heath brothers ground this in Elizabeth Newton's 1990 Stanford experiment, the *tappers and listeners* study: tappers were asked to tap the rhythm of a well-known song on a table while listeners tried to identify it. Tappers predicted listeners would get it 50% of the time. The actual rate was 2.5%. The tapper hears the melody in their head. The listener hears Morse code.

Every paragraph of mediocre documentation is a tapper writing for someone who can only hear taps. The antidote is structural: do not open with what the page is about. Open with what the reader is trying to do.

Look at how React's "Thinking in React" begins, *"React can change how you think about the designs you look at and the apps you build."* The opening sentence names a shift in the reader, not a feature of the library. Or Anthropic's prompt-engineering page, which leads with a preconditions block: *"This guide assumes that you have a clear definition of the success criteria…"*, the reader's state is acknowledged before the page proceeds.

Compare those with the failure mode you've seen a thousand times: *"This document describes the configuration options for the X system."* That sentence has done zero work. It's metadata.

So: before you write anything, name in one sentence what the reader was doing two minutes ago. Then write a first sentence that meets them there.

2. Identify which kind of doc you're writing

There are four. They are not interchangeable, and most documentation problems are mode-confusion problems, a tutorial that's really a feature tour, a reference page that lectures, a how-to guide that opens with a paragraph of theory. The four-mode framework comes from [Diátaxis](https://diataxis.fr/) and has been adopted by Python, Ubuntu, Canonical, and Cloudflare.

| Mode | Question it answers | Reader's state | Form | |---|---|---|---| | **Tutorial** | "How do I learn this?" | Novice; seeking confidence | Narrative, imperative, step-by-step. Ends with the reader having built something real. | | **How-to guide** | "How do I do X?" | Competent; pursuing a specific goal | Directive, conditional, assumption-laden. Skips theory; links to it instead. | | **Reference** | "What is/are…?" | Practitioner; seeking facts | Declarative, atomic, scannable. Each entry stands alone. | | **Explanation** | "Why? What does this mean?" | Reader; seeking understanding | Discursive. Explores trade-offs. Does not prescribe action. |

When the call is close, ask the decisive question. *Tutorial or how-to?* Is the reader learning the domain, or already trying to do something specific. *How-to or reference?* Does the reader know why they're here. *Reference or explanation?* Is this what it is, or why it matters. *Explanation or tutorial?* Is this building understanding, or capability.

If y