Limitations of automatic documentation
As technology advances and workflows are streamlined, some have turned to automated tools such as Doxygen, Sphinx, Swagger, etc. in order to generate technical documentation automatically.
What are the most glaring limitations to these tools, and how can they be addressed in the spirit of saving time for those performing the documentation?
This post was sourced from https://writers.stackexchange.com/q/33572. It is licensed under CC BY-SA 3.0.
2 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
Automated systems such as Sandcastle and Swagger are good at converting code syntax into documentation. Those will produce marginal documentation. What they don't do is add insight into the calls. Rarely does a method exist by itself. There are always additional notes needed, caveats explained, side affects, clarifications for each the parameters, return values, the method itself, and even using the method in a larger context. Compare, for example a typical MSDN reference page with a anyone REST reference page. For each method the MSDN page is longer and more detailed, the material developers want. The REST ones are usually scarce with fewer additionally notes.
Then there are examples and code snippets. No auto generated application can make those. A lot of people don't understand API documentation. 95% of the time, developers just want a sample to copy and paste. Automated documentation rarely generates those.
Many think that being able to use a reference page is enough. It's not. It's the ease and completeness in how the questions are answered that counts. This is the difference between adequate documentation and great documentation.
This post was sourced from https://writers.stackexchange.com/a/33574. It is licensed under CC BY-SA 3.0.
0 comment threads
Doxygen, etc. do not really generate documentation automatically. They restructure and format information that was written by hand, either in the form of code (which is a form of structured data) or comments written into the code. They format and publish the information automatically. They don't generate content automatically.
To me, the most glaring limitation of these tools is that they constitute a separate publishing tool chain unrelated to the tool chain used for the rest of the documentation set. This means first that you have to do all the work of configuring and maintaining the toolchain and the presentation and and formatting of your content twice. And because these all have relatively crude publishing engines, you often can't really get their output to match the design of the rest of the documentation set.
The second problem with this is that it means there is no integration between the content they produce and the rest of your content. Back in the paper days this was less of a concern, but now that we publish mainly to the Web, it makes it more difficult to do elementary things likes generating links from mentions of a function in the programmers guide to the listing of that function in the API reference.
The cure for these problems is to take XML output from these tools and to feed it into the general tool chain. Of course, this supposes that your general tool chain is XML based or is at least capable of receiving and integrating an XML feed. This is not the case for most off the shelf writing and publishing tools. The result is that your API docs are left as an island.
0 comment threads
0 comment threads