Good Documentation Is Compressed Experience

I spent several days trying to reconstruct the meaning of a number.

The calculation was available. The records were available. Pieces of the process had even been written down.

What was missing was the sentence that connected them.

The real definition lived across old files, partial explanations, and the memories of people who had worked with the process before.

Once the answer was found, it was almost embarrassingly simple. It could be explained clearly in less than a minute.

I stopped thinking of documentation as a record of instructions.

The most valuable documentation captures the experience required to reach the answer.

A short definition may look obvious after it has been written. That does not mean it was obvious before someone did the work of finding it.

Good documentation compresses that work so the next person does not have to repeat it.

When something takes days to discover but seconds to explain, I will write down the explanation. The length of the answer does not measure the value of preserving it.