The Case for Writing Documentation Before the Code
Not a process recommendation. A thinking tool that happens to leave documentation behind.
I do not write docs first because I am disciplined. I write them first because it is the cheapest way I know to find out that I do not understand the problem.
Prose does not let you hand-wave
Code lets you defer a decision indefinitely. You write a function, you give it a plausible name, and the ambiguity lives inside it quietly for months.
Prose will not do this for you. The moment you try to write "when a user saves a draft, the system…" you discover you do not know what happens if they have two tabs open. In code that question would have surfaced as a bug in November.
The README test
Write the README as though the feature exists. Describe how someone uses it, what they pass, what they get back.
If the README is hard to write, the design is wrong. Not "needs polish" — wrong. Difficulty explaining an interface is almost always the interface being difficult, and no amount of implementation skill will fix an API that cannot be described in a paragraph.
What it costs
An hour, usually. Occasionally a day, and those are the ones that save a fortnight.
The documentation you end up with is a side effect. Useful, but not the point. The point is that you found the hard question while it was still free to answer.