Ritwik Deshpande and I have been fascinated by a single question over the past three or so weeks: why is technical documentation so terrible? Whenever I tell someone about this, they always ask: what do you mean by "technical documentation"?
The term "documentation" refers to different things in different contexts: it’s really just the umbrella term for "writing something down.” If I were to say “documentation” to an anthropologist, she might think I’m referring to the act of listing everything I observe. A project manager might think I am talking about internal project documentation, where team members record details or instructions within project materials to keep all collaborators on the same page.
What I’m referring to, however, are the public-facing reference manuals that we encounter when we use computer programs. These programs include APIs, code libraries, and even programming languages. Their complexity means they require detailed manuals to instruct users on how to use them. These manuals are what Ritwik and I are interested in: the external-facing, online, technical references:
external-facing, because these manuals are usually developed for external users. Internal documentation might be crucial for collaborators to quickly get ramped up on the projects: however, these get treated less carefully because there's always the opportunity for team members to speak in-person about things they do not understand. More care is taken in crafting manuals for external users, and thus any recommendations for improvement that we might have might be taken more into consideration.
online, because that’s the format these manuals are taking these days. The earliest computer program references were of course printed, such as the early manuals for the C programming language, but today they are all online. And being online means having a unique set of design considerations: what do users experience if they enter the references at a particular page? How do they navigate the full reference? Can we make things interactive?
technical, because these require a different approach compared to manuals for applications with GUIs. GUI applications could be explained by annotated images of the different views within the application. In contrast, applications without a GUI often come with text-heavy references because much of what is being explained is highly conceptual.
Ritwik and I code, and we regularly need to refer to references when using a new API, or a new programming language. And almost universally, we have struggled with these references: they are verbose, difficult to understand, and often contain tautological statements. But these are complaints for another post, another day.
Is there a better term for these manuals than “technical documentation”? Perhaps “technical references”? “Technical manuals”?