Survival strategies for API documentation
If you're documenting an API for the first time, you may be in survival mode just trying to decipher the code, unravel developer speak, and publish a coherent set of documentation. API documentation is a new landscape for most technical writers.
Traditional platform APIs are often published through a document generator such as Javadoc or Doxygen, while REST or web APIs are published using everything from document generators that parse Swagger and RAML specs to custom toolsets to manually-formatted web pages either from static site generators (such as Nanoc) or homegrown sites.
The reference documentation is actually the easy part. The real difficulty, and most likely the one you'll be tasked with, is showing developers how to use the API, the way the various endpoints or classes work together, and how you can piece it all together with the right parameters to achieve an actual business goal.
In this presentation, I'll give you an introduction to API documentation, try to answer your questions, and give you tips for getting started in the right direction.
About Tom Johnson
Tom 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 (www.idratherbewriting.com), is a hub for innovation and exploration in the tech comm field.
Tom recently guest edited an issue of the STC Intercom that focused entirely on API documentation. He has also done a series of podcasts on API documentation, interviewing experts in this space. In his current role, he provides documentation for both platform and web APIs, in addition to other developer tools.
Tom lives in San Jose, bikes to work, and has four girls. You can contact him at firstname.lastname@example.org.
- When: Monday, February 2, 2015
- Where: In your own home. This will be a Webcast using GoToMeeting. There is no toll-free number; however, you can use VoIP.
- Time: Presentation starts at 7:00 p.m. EST. Please allow yourself enough time to get logged in prior to the 7:00 start time.
- Cost: $10.00 (STC Members) $20.00 (Non-members)
Payment and Registration
Please register using Eventbrite.
The login information for GoToMeeting will be sent to you the day before the event.
If you have any questions about this event, contact Greg Campbell, Program Manager, STC Southwestern Ontario Chapter.