publishing api documentation -- presentation
TRANSCRIPT
{by Tom Johnsonidratherbewriting.com
Publishing strategies for API documentation
STC Summit 2015 Columbus, Ohio @tomjohnson
• Resource description• Endpoint• Methods• Parameters• Request example• Response example• Status and error codes• Code samples
Reference sections
Static site gen. -- Jekyll
JekyllDocpadMiddleman Staticgen.com
Help authoring tools
• 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