Costly honesty

Anyone can say their work is good. It costs nothing, so it doesn’t mean much. What people actually believe are the things that would have been expensive to say if they weren’t true. Biologists see this in animals and economists see it in job interviews. It holds for documentation too.

We tried something once. We were rewriting the docs for a system that had been running for a while, and on the very first page, before anything else, we listed what was wrong with it. A step that didn’t do what the design said. A part whose name had stopped describing what it did. A file that looked like the instructions but wasn’t the one actually used.

None of it was secret. Everyone who’d worked on the system knew. But you only knew if you’d been there, and the next person wouldn’t have been.

It made things look worse for about a minute. After that, people trusted the rest of the document more, because it clearly hadn’t been written to impress anyone. And something we didn’t expect: once those flaws were sitting on the front page, nobody liked leaving them there. Several were fixed within weeks.

The person easiest to fool is usually yourself. Docs that hide their problems fool the people who wrote them first.