Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Limitations of automatic documentation

+0
−0

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?

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/33572. It is licensed under CC BY-SA 3.0.

0 comment threads

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.

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33574. It is licensed under CC BY-SA 3.0.

0 comment threads

Sign up to answer this question »