SUBSCRIBE TO MY NEWSLETTER

Sponsored content

Search results

API doc survey: How much of your doc process is automated?

API documentation survey

by Tom Johnson on Jan 15, 2015 •
categories: api-doc

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.

Sponsored content

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.

Buy me a coffeeBuy me a coffee
follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Comments