API doc survey: How much of your doc process is automated?
This question in my API doc survey was so poorly worded that the answers are mostly confusing. Unfortunately, this was the first question in the survey and probably the most vague. Here's the question:
Do you generate Javadoc or Doxygen files manually, or are they auto-rendered as part of the build process?
REST API documentation is notably different from platform-specific API documentation. With platform-specific API documentation, such as for Java, C++, and .NET, document generators are commonly used. Usually you use Javadoc for Java, Doxygen for C++, VSDocman or Sandcastle with .NET, and so on.
At my work, Javadoc and Doxygen are actually integrated into the software build process. Meaning, when engineers push a release into a general availability status on Bamboo, a build process on the Bamboo server initiates a script that builds a Javadoc or Doxygen file from the source code. I don't have to manually build the Javadoc or Doxygen files. (With one exception -- the .NET file wasn't properly integrated into the build process, so I manually built it using the Doxygen document generator.)
I was curious to know how common it is for the build process to automatically take care of generating the Javadoc or Doxygen. In part I was curious because a few months ago I attended an API workshop where a couple of hours were dedicated to setting up your computer to generate Javadoc properly.
However, here's the confusing part. Most technical writers in the survey are documenting REST APIs, and some of them have automated processes for the documentation. For example, some have custom tooling, Python scripts, Swagger, or are using other document generators like JSDoc. These tools perform some kind of automation in the way they build the API documentation output, but the tools aren't necessarily integrated into the engineering build process for the source files.
A much better question in my survey was the question that asked whether any part of the REST API documentation was auto-generated.
At any rate, I tried to tally up the responses for this question and came up with the following. From the 43 responses, 58% are producing the API documentation manually, and 44% are using some kind of automation, whether it's using a document generator or some generation included in the build process. However, this question was so poor that the responses aren't worth analyzing in greater depth.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
About Tom Johnson
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.