When we played KVN, a single joke could take an entire evening. We moved words around until the line finally sounded the way we had imagined it. By then, it knew its way home and had started asking for a fee.
Documentation works much the same way. Except that after a joke, someone should laugh; after an instruction, they should know what to do. Ideally, the same thing the author had in mind.
Once, while we were encouraging colleagues to put requests in writing instead of passing them along like secret knowledge, I received a fourteen-page document. It looked impressive. Finding the actual task inside took a little more effort.
I asked whether I should reply point by point or get to the substance. We chose the latter. My response took a couple of pages, and the conversation showed that we first needed to clarify the requirements. In the end, we handled most of what was needed with two ready-made plugins.
The fourteen pages did not make the task more complex. They simply hid it.
I have nothing against detail; sometimes it is essential. But every line should have a job. Length alone does not guarantee accuracy, and an important-looking document does not guarantee clarity inside.
To me, good documentation is not a sacred scroll. It is something I can read, understand what to do, and trust without guessing at missing decisions. I should also be able to expect other readers to understand it in the same way.
Putting that meaning on one page can take more work than filling fourteen. Fortunately, readers do not need to know how many hours you spent pushing that sentence around the table.