Technical Writing Is Interface Design

I spent years thinking of documentation as something you write after the real work. The code was the product; the docs were the receipt. I have since come around to the opposite view: for anything with a user, the writing is the interface.

A README is not a description of a tool. It is the first interaction a person has with it, and often the only one. It has states, affordances, and a failure mode: the reader gives up.

Docs are a UI with one screen

Think about what a good interface does. It tells you where you are, what you can do next, and what happens if you do it. Good docs do exactly that, in the same order.

1. Orient. One sentence on what this is and who it is for.
2. Show the shortest path. A copy-pasteable example that works on the first try.
3. Explain the edges. The config that bites, the limit that surprises, the error that means something specific.
4. Point outward. Where to go when this page is not enough.

The first ninety seconds

The cost of bad writing is not aesthetic. It is the twenty minutes a stranger spends guessing, the support thread that should have been a paragraph, and the tool that gets abandoned because the quickstart did not run.

The same is true of docs. Almost every page you need to write has a shape that already works. You are not inventing a genre; you are choosing the right one and filling it in.

A practical rule

Write the example first. If the example is awkward, the API is awkward, and no amount of prose will hide it. Writing is how I find out that a function needs a different name, or that a config flag should really be two.

None of this is new advice. It is just easy to skip when the deadline is close and the code already 'works'. But the code does not work for the person who has never seen it, and that person is the whole audience.