Repeatedly, me and my colleagues complain about the lack of documentation: Why is the software constructed in this particular way, how are users supposed to know how to set this up etc. We say there should be “more” documentation but, alas, there is just not enough time to write it down. On the other hand, we spend the time with something else for which there was enough time, it seems.

Plausibly one could say that documentation writing is not a developer task—developers write code. However, me and my peers gladly write a lot of other non-code things: Issues about problems, tickets about new features, review comments, code comments and mails about what to do about some piece of code. So these get created.

But what makes documentation different than these other things? After all, code comments, unit tests and tickets are also describing and explaining. They are not the “documentation” but they are similar in their function.

The difference between documentation and the other genres of writing (e.g. unit tests, issues…) might be what they “do”. What will happen if I create one of those representations? When I write a unit test, future code changes are constraint by it. It directs power by creating an algorithmic complaint when assumptions are not met, and triggered by the complaint, people will discuss if they did violate the assumptions or if the assumptions are problematic. When I write an issue report, people act based on this, they will try to evaluate it’s severity, will ask me questions, try to solve the problem or, alternatively respond and frame it in a way that redirects the problem to me and argue that it should not have been an issue in the first place. So writing an issue also directs power and causes people to act. However, documentation does rarely triggers, directs or constraints actions. What is called "documentation" is largely holding information for people and situations outside of the day-to-day concerns.

If documentation does not direct power but other, similar things do, it begs the question if anything that directs power would be still called “documentation” at all. It might instead get a more descriptive name of what it shall do.

(This is just a short essay, so it does not have the ususal references. And maybe I'll change and expand it in the future)