Publishing API documentation -- Presentation
30
{ by Tom Johnson idratherbewriting.com Publishing strategies for API documentation STC Summit 2015 Columbus, Ohio @tomjohnson
-
Upload
tom-johnson -
Category
Technology
-
view
771 -
download
6
Transcript of Publishing API documentation -- Presentation
{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
