Developers tend to have a very low opinion of technical documentation: it is often wrong, partial, unclear and not worth the trouble of reading. This is, in part, a self-fulfilling prophecy: such low opinions of technical documentation results in them not being read, and not being invested in. I have no easy solution for this: technical documentation is an art and a science, and not everyone is good at it. It’s all about communication and, while communication is the first thing we start learning, as soon as – and perhaps before – we are born, it is also something we never stop learning and refining.

The solution I do have is not easy: good documentation requires a consistent, considerable, continuous investment both pecuniary and of effort. Good documentation requires time, tools and tenacity – all of which cost money.

The same is true for good code, of course, but the difference between good code and good documentation from the software/firmware engineer’s perspective is that good code not only has a direct effect on the productivity of the engineer: it also has a direct effect on the quality of the product and it is a clear responsibility of the engineer (which means that if you don’t get it right, you either lose your job or get to do it over and over until you do get it right).

the argument for investment in tools and time is also easier to make for code than for documentation: customers have come to expect glossy marketing paired with low-quality technical documentation because the two types of documentation don’t target the same audiences. Once they make a purchase decision based on the glossy marketing, they’ll expect the product to work, but the decision-makers will not be looking at the technical documentation for that. Hence, the only people who end up looking at the technical documentation are the ones who typically have the least influence over purchase decisions: the standards for documentation are lower because the perceived impact is lower (though the emphasis on perceived is there for a reason). The expectations are also lower, due to the often-dismal state of existing technical documentation.

Quality is the measure by which a product meets or exceeds the needs, requirements and expectation sur of the customer. Requirements are functional or non-functional in nature and are often ill-defined: Ford’s customers wanted a faster horse, Ford came up with a car. However, one ever-recurring non-functional requirement is usability. This is the requirement the documentation addresses. Good documentation can increase the usability of the produce it documents tremendously. Bad documentation at best has no negative effect and at worst can make a product border uselessness. On the other hand, expectations are low, so it’s easy to meet or exceed them.