{ by Tom Johnson idratherbewriting.com Publishing strategies for API documentation STC Summit 2015 Columbus, Ohio @tomjohnson
Publishing API documentation -- Presentation
Aug 03, 2015
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
{by Tom Johnsonidratherbewriting.com
Publishing strategies for API documentation
STC Summit 2015 Columbus, Ohio @tomjohnson
a. Guides
b. Tutorials
c. Reference
Breaking down API docs
• Resource description• Endpoint• Methods• Parameters• Request example• Response example• Status and error codes• Code samples
Reference sections
Source code to JSON
Scripts import JSON
Web CMS pushes JSON
into templates
Custom scripts
Static site gen. -- Jekyll
JekyllDocpadMiddleman Staticgen.com
Custom UX solutions
Help authoring tools
3. Lots of code samples
Versioning
Translation
Authent-ication
Language switching
Challenging factors
• Will developers be writing or contributing to the content?• Does your security group restrict you from using third-party
platforms to host documentation?• Do you have a budget to pay a third-party platform for
hosting?• Do you want to manage the web platform details yourself or
offload this onto another group/company?• How many endpoints do you have to document? How
structured is your content?• Should you push documentation from the source into your
documentation?• Does the documentation need be visible on the web, or does it
need to be private?• To what extent do you want customers to have a one-stop-
shopping experience — reading docs, logging support tickets, posting to forums, viewing news?
• Do you have UX resources to help you build a solution?
Questions to consider
Most images are screenshots linked to a webpage, but some are from Flickr and Vecteezy. Required attribution is as follows:
• Structure, https://flic.kr/p/oFD6MM Rafal Zych• Earth patterns. https://flic.kr/p/ssQqiL Evriel
Venefice• Dave’s Bike Tools, https://flic.kr/p/QMVMw Bri
Pettis• Vector icons from Vecteezy.com
Image credits
Related Documents
