When you’re building a Web API, you’re likely going to need to figure out how to provide documentation to your end-users. If you didn’t think of that when you started your project, it can be a real deflating moment when it finally comes to mind. Documentation is boring and tedious. It’s nowhere near as fun as code.

Because documentation is boring, most software developers will quickly turn towards documentation tools. It’ll be so much faster to write documentation if we can just build or apply some software to do it, and building a software tool is much more fun than just sitting down and writing.

Documentation tools have advantages over hand-written documentation: they’re easier to keep up-to-date, they can produce output much faster, and they can provide much better coverage with less effort. But, before you go looking at API documentation tools, take a step back and figure out some high-level details about what your documentation looks like.

Who is authoring, editing, and maintaining the documentation project, now and in the future?

This is the most important point to consider before you choose a documentation tool. Is your documentation going to be written by a technical writer, a developer, or a product owner? Is it going to be authored and edited in-house, are you going to outsource to someone with more expertise?

If you have a technical writer involved in the documentation of your API, you need to consider the environment, systems, and processes that they’re used to working with. Maybe they’re not comfortable writing Javadoc comments; knowing that will definitely impact upon tool selection.

Example: A first-draft of documentation comes from the API developer, because they know what the API can do and how to describe it to other developers. After that, it’s usually rewritten and then maintained by a technical writer; that will influence my documentation tool search towards tools that a writer can work with.

How and where is it going to be published?

Is your documentation output part of your product, part of your marketing website, part of your support team’s website, or something completely independent? This will vary dramatically between smaller organizations and larger ones, but there are important considerations that need to be figured out.

If you’re a development shop that wants to do continuous deployment, do you want a technical writer to be pushing builds out when they update the documentation project?

Example: In an organization with separated web responsibilities between marketing and product, documentation probably belongs hosted with the marketing web site. It doesn’t have the same availability and compliance requirements as product changes.

When is it going to be updated and released?

Do you release your documentation at the same time as your software upgrades? I think that’s the “default” choice for many people because it allows them to have an integrated release process, but you’ll find that it creates some friction. It can be more difficult to update documentation to cover new capabilities when they aren’t available to be tested, screenshotted, or described by the doc authors.

If you have a rigorous change control process, do documentation changes really need to go through that rigmarole? Does every documentation update need a JIRA issue and a Q/A sign-off?

What formats do you want to present the documentation in?

HTML, obviously. Virtually everyone wants HTML documentation.

But, do you also want a more standalone documentation format? It can be quite handy to have PDF output that can be e-mailed to a prospective client, or can be archived on a network folder somewhere.

Once you’ve gathered all that information, you might start to have a picture of what you want your documentation tools to look like. Maybe it’s an integrated documentation tool, but maybe not.

Personally, I like Sphinx as a documentation tool. It can fit into a wide variety of workflows, it can skirt the edge between automatically-generated and manually-written documentation, and it can output in multiple formats including HTML and PDF. sphinxcontrib-httpdomain is an excellent contrib add-on specifically for documenting HTTP APIs.