Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

API Doc presentation slides and recording (San Francisco STC chapter)

Oct 16, 2014 • api-doc, dita, podcasts

Yesterday I presented "Publishing strategies for API documentation" to the San Francisco STC chapter. Here are my slides and recording.

Length: 60 min.

Download MP3 (right-click and select Save As)

Publishing strategies for API documentation from Tom Johnson

PowerPoint in other format: pptx | zip

Also, I know I posted it earlier, but here's the description of my presentation.

Publishing strategies for API documentation

Most of the common tools for publishing help material fall short when it comes to API documentation. Much API documentation (such as for Java, C++, or .NET APIs) is generated from comments in the source code. Their outputs don't usually integrate with other help material, such as programming tutorials or scenario-based code samples.

REST APIs are a breed of their own, with almost no standard tools for generating documentation from the source. The variety of outputs for REST APIs are as diverse as the APIs themselves, as you can see by browsing the 11,000+ web APIs on

As a technical writer, what publishing strategies do you use for API documentation? Do you leave the reference material separate from the tutorials and code samples? Do you convert everything to DITA and merge it into a single output? Do you build your own help system from scratch that imports your REST API information?

There's not a one-size-fits-all approach. In this presentation, you'll learn a variety of publishing strategies for different kinds of APIs, with examples of what works well for developer audiences. No matter what kind of API you're working with, you'll benefit from this survey of the API doc publishing scene.

Mysti Berry has a great write-up on my presentation on the STC San Francisco blog.

Other notes

By the way, this was my first time presenting on this topic. About 20 people attended the meeting, which was a good turnout. I felt the overall presentation went well. A couple of people who have been doing API doc for a while said their most common scenario in companies is to deliver API files and documentation securely behind a firewall, generating it via Javadoc or Doxygen. This makes it hard to create the beautiful API doc websites that you see online.

Others had a lot of questions about Swagger, particularly the specification that needs to be written, its format and content, etc. This is something I need to learn more about.

If you have any feedback on the slides or audio, let me know. I'll be giving different versions of this presentation at some other places this coming year.

Add a review for the "I'd Rather Be Writing" podcast in iTunes

If you like this podcast, please add a review for the podcast in iTunes. Just click this link, and then launch iTunes. Find and subscribe to the podcast in iTunes. On the Ratings and Reviews section, add a rating and optionally a review. This will help increase the visibility of the podcast in iTunes.

You can help support my podcast by reviewing it in iTunes.
You can help support my podcast by reviewing it in iTunes.

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.