I’m about  as bad at documenting my code as the average software developer, but I’m trying to be better. With Hypothesis I think I’m making good progress on that front, though I feel like it’s still very visibly someone who isn’t actually good at documentation but is trying to do better.

One of the first steps of doing better is not to fool yourself with substitutes. The following is a short, incomplete, list of things that developers falsely believe to be documentation:

1. The code itself
2. The tests for the code
3. The comments in the code
4. The type signatures
5. The person who wrote the code being available for questions
6. Discussions in your issue tracker

Here is a short, complete, list of things that are actually documentation:

1. A document, written in a natural language, which describes how to use your software.

If it is not on this second list, it’s not documentation.

All of the first list are useful tools which aid program comprehension. The presence of good documentation does not remove the need for them. However the presence of them also does not remove the need for good documentation.

The confusion comes, I think, from people confusing “substitutable to a point” with “substitutable”. Type signatures, or tests, can fill some of the use cases of documentation, and can reduce its need for a time, so it’s tempting to think of them as a sort of documentation, but they cannot actually fill the niche of comprehension that documentation enables.

Let me try an analogy: Consider coffee and sleep, subjects dear to my heart. Can you substitute coffee for sleep? Certainly, up to a point – if you’ve had a bad night, coffee will help. Can you substitute sleep for coffee. Certainly. I’ve heard rumours from people who are familiar with the concept that if you have a good night’s sleep then you need less coffee the next day. Can coffee improve alertness even in the presence of enough sleep? Yep.

Is coffee a type of sleep? Uh, no.

The fact that two tools solve overlapping problems is no excuse for confusing them.

Why am I taking such a hard line about this?

It’s because developers hate writing documentation but know that it’s a thing they’re supposed to do.

So if you let people believe that something that is not documentation is documentation, they’ll just do that instead and tick the box that says “Yep! I documented it”, and feel good about themselves for having writing code that does not, in fact, have documentation.