Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

Upcoming presentation in downtown San Francisco: Publishing strategies for API documentation

Sep 2, 2014 • api-doc

10/15/2014 update: For the slides and recording, see this post.

I'm giving the following presentation to the San Francisco STC Chapter on October 15:

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 programmableweb.com.

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.

Presentation Details

Group: San Francisco STC Chapter
Location: Hub SoMa at 901 Mission St, Ste 105, between 5th and 6th Streets
Date: Wednesday, October 15
Time: 6-7pm (networking); 7-8pm (presentation)
Cost: Members, $15; Non-members, $20; Students/first timers*, $10. Tickets are available at the door.

missionstreet

About Tom Johnson

tom_johnson_picture2Tom Johnson is a senior technical writer for the 41st Parameter, a company in the fraud detection and advertising technology space. Tom's blog, I'd Rather Be Writing (idratherbewriting.com), is a hub for innovation and exploration in the tech comm field.

Tom recently guest edited an issue of the STC Intercom (September 2014 issue) that focused entirely on API documentation. In his current role, he provides documentation for Java, C++, and .NET APIs, in addition to other developer documentation. In a previous company, he worked on documentation for a REST API and JavaScript SDK.

Tom lives in San Jose, bikes to work, and has four girls. You can contact him at tom@idratherbewriting.com.

Note: This presentation will be recorded and posted here for those who can't make it to San Francisco.


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.