In earlier parts of this course, I used a simple Weather API from Mashape to demonstrate how to use a REST API. Now I’ll explore various tools to publish documentation about this same Mashape Weather API.
The first question about a focus on publishing API documentation might be, why? What makes publishing API documentation so different from publishing other kinds of documentation such that it would merit its own section? How and why does the approach with publishing API docs need to differ from the approach for publishing regular documentation?
This is a valid question that I want to answer by telling a story.
When I first transitioned to API documentation, I had my mind set on using DITA, and I converted a large portion of my content over to it.
However, as I started looking more at API documentation sites, primarily those listed on Programmableweb.com, which maintains the largest directory of web APIs, I didn’t find many DITA-based API doc sites. In fact, it turns out that almost none of the API doc sites listed on Programmable Web even use tech comm authoring tools.
Despite many advances with single sourcing, content re-use, conditional filtering, and other features in help authoring tools and content management systems, almost no API documentation sites on Programmableweb.com use them. Why is that? Why has the development community implicitly rejected tech comm tools and their many years of evolution?
Granted, there is the occasional HAT, as with Photobucket’s API, but they’re rare. And it’s even more rare to find an API doc site that structures the content in DITA (so far, CouchDB is the only one I’ve come across).
I asked a recruiter (who specializes in API documentation jobs in the Bay area) whether it was more advantageous to become adept with DITA or to learn a tool such as a static site generator, which is more common in the API space.
My recruiter friend knows the market — especially the Silicon Valley market — extremely well. Without hesitation, he urged me to pursue the static site generator route. He said many small companies, especially startups, are looking for writers who can publish documentation that looks beautiful, like the many modern web outputs on Programmableweb.
His response, and my subsequent emphasis on static site generators, has led me to understand why traditional help authoring tools aren’t used often in the API doc space. Here are 5 reasons:
If devs are going to contribute to docs (or write docs entirely themselves), the tools need to fit their own processes and workflows. Their tooling is to treat doc as code, committing it to version control, building outputs from the server, etc. They want to package the documentation in with their other code, checking it into their repos, and automating it as part of their build process.
Why are engineers writing documentation in the first place, you might ask? Well, sometimes you really need engineers to contribute because the content is so technical, it’s beyond the domain of non-specialists. If you want engineers to get involved, especially to write, you need to use developer tooling.
Ideally, engineers want to add annotations in their code and then generate the doc from those annotations. They’ve been doing this with Java and C++ code through Javadoc and Doxygen for the past 20 years (for a comprehensive list of these tools, see Comparison of document generators in Wikipedia).
Even for REST APIs, there are tools/libraries that will auto-generate documentation from source code annotations (such as from Java to a OpenAPI spec through Codegen), but it’s not something that HATs can do.
The reference documentation for APIs is pushed into well-defined templates, which list sections such as endpoint parameters, sample requests, sample responses, and so forth. (I discuss these reference sections in Documenting endpoints.)
If you have a lot of endpoints, you need a system for pushing the content into standard templates. Ideally, you should separate out the various sections (description, parameters, responses, etc.) and then compile the information through your template when you build your site. Or you can use a specification such as OpenAPI to populate the information into a template. You can also incorporate custom scripts However, you don’t often have these options in HATs, since you’re mostly limited to what workflows and templates are supported out of the box.
You won’t find an interactive API console in a HAT. By interactive API console, I mean you enter your own API key and values, and then run the call directly from the web pages in the documentation. (Flickr’s API explorer provides one such example of this interactivity.) The response you see from this explorers is from your own data in the API.
Most output from HATs look dated and old. They look like a relic of the pre-2000 Internet era. (See Tripane help and PDF files: past their prime? from Robert Desprez.)
With API documentation, often times the documentation is the product — there isn’t a separate GUI that clients interact with. That GUI is the documentation, so it has to be sexy and awesome.
Most tripane help doesn’t make that cut. If the help looks old and frame-based, it doesn’t instill much confidence toward the developers using it.
Based on all of these factors, I decided to put DITA authoring on pause and try a new tool with my documentation: Jekyll. I’ve come to really love using Jekyll, working primarily in Markdown, leveraging Liquid for conditional logic, and committing updates to a repository.
I realize that not everyone has the luxury of switching authoring tools, but when I initially made the switch, the company I was working for was a former startup, and we had only 3 authors and a minimal amount of legacy content. I wasn’t burdened by a ton of legacy content or heavy processes, so I could innovate.
Now that I’ve hopefully established that traditional HATs aren’t the go-to tools with API docs, let’s explore various ways to publish API documentation. Most of these routes will take you away from traditional tech comm tools and publishing strategies and into more developer-centric tools.
40/91 pages complete. Only 51 more pages to go...
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson