We have many clients asking about auto-generated documentation to document their code (for those unfamiliar with this process, programmers write the documentation as part of their code and then use tools like Doxygen to extract that content and automatically generate a formatted output).
While the thought of auto-generated documentation conjures up images of cost savings and a reduced work load, your customers may not be so pleased when they see final result. In this article we take a look at why you may want to exclude auto-generated documentation from your next dev cycle.
Whenever we see auto-generated documentation, our first thought is that the developer was too lazy to put together a well documented and formatted API guide. More generally it leaves the user with the impression that the developer was trying to take a short-cut and cared more about the code than the documentation. The reason for this is two fold: auto-generated documentation is almost never well documented because programmers are generally better at writing code than documentation. Secondly, the output usually makes it difficult to find anything. With limited control over elements like the table of contents, what you usually end up with is a raw dump of all files, functions, headers etc. instead of a nicely formatted documentation package. Plus those involved with the writing of the documentation don’t really have a full view of how their content will fit into the final output, which contributes to a mishmash of styles and layouts.
While tools like Doxygen are good at generating fancy graphs of dependencies and huge lists of functions, the user generally doesn’t care about these things. What they really want is a solid introduction, good explanations for what the API does and well documented API calls with samples. Oh, and they want it all in a nice package.
Some have attempted to integrate Doxygen generated documentation into external documentation, but the results are seldom satisfactory. Others choose these code generation tools under the assumption that the code and its related documentation should stay in sync because they all come form the same source. While that’s good in theory, it seldom happens in practice. Function signatures are constantly being added to and changed, and unless the team is disciplined, the documentation usually falls by the wayside.
There are a few other challenges as well. Since code is being marked up there is the potential to break the build. And if you’re using a complex build system, it could take a while to discover that some innocent documentation changes have broken your build, or at the very least that they did not produce the right output. In addition, it’s another tool which your build person must learn and maintain as part of an already complex build process.
These tools also require developers to use special tags which they may not be familiar with. Also – they generally don’t allow you to tag your actual code as example code, so you often have to duplicate code in comments – another area where things can get out of sync.
So in our experience, when you add all these things up you really are better off having a technical writer manually assemble a proper set of documentation separate from your codebase. You will get the exact result you are looking for and your customers will be much more satisified.