Publishing API documentation -- Presentation
•Download as PPTX, PDF•
4 likes•2,299 views
I gave this presentation at the STC Summit 2015.
Recommended
Recommended
More Related Content
What's hot
What's hot (19)
Similar to Publishing API documentation -- Presentation
Similar to Publishing API documentation -- Presentation (20)
More from Tom Johnson
More from Tom Johnson (7)
Recently uploaded
Recently uploaded (20)
Publishing API documentation -- Presentation
- 1. {by Tom Johnson idratherbewriting.com Publishing strategies for API documentation STC Summit 2015 Columbus, Ohio @tomjohnson
- 2. The variety of API docs
- 3. a. Guides b. Tutorials c. Reference Breaking down API docs
- 7. • Resource description • Endpoint • Methods • Parameters • Request example • Response example • Status and error codes • Code samples Reference sections
- 8. If developers will write …
- 9. Miredot – Java doc gen.
- 10. Github wikis
- 11. Source code to JSON Scripts import JSON Web CMS pushes JSON into templates Custom scripts
- 12. Swagger - Swagger - RAML - API Blueprint
- 13. API Blueprint and Apiary - Mulesoft - Apigee - Apiary
- 15. Static site gen. -- Jekyll Jekyll Docpad Middleman Staticgen.com
- 18. readthedocs.com
- 20. API doc design patterns
- 21. 1. Structure and templates
- 23. 3. Lots of code samples
- 28. • 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
- 30. 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
Editor's Notes
- http://www.programmableweb.com/apis/directory
- https://sendgrid.com/docs/User_Guide/index.html
- https://www.parse.com/tutorials
- https://instagram.com/developer/endpoints/relationships/
- https://www.youtube.com/watch?v=EnB8GtPuauw
- http://www.miredot.com/exampledocs/
- https://github.com/ and https://github.com/basecamp/bcx-api/
- http://swagger.io/ and http://editor.swagger.io/
- https://apiary.io/
- http://raml.org/index.html
- Aviator theme from Cloud Cannon: https://github.com/CloudCannon/Aviator-Jekyll-Theme List of static site generators: http://www.staticgen.com/ Jekyll: http://jekyllrb.com/
- http://readme.io
- https://readthedocs.com/
- Photobucket API doc example: https://pic.photobucket.com/dev_help/WebHelpPublic/PhotobucketPublicHelp_Left.htm#CSHID=FAQ/FAQOverview.htm|StartTopic=Content/FAQ/FAQOverview.htm|SkinName=WebHelp Flare: http://www.madcapsoftware.com/products/flare/
- https://flic.kr/p/ssQqiL Earth patterns, flickr. evriel venefice
- https://flic.kr/p/oFD6MM Structure Rafal Zych
- Yelp API doc: https://www.yelp.com/developers/documentation
- https://www.twilio.com/docs/api/rest
- http://documentcloud.github.io/backbone/
- https://dev.twitter.com/rest/tools/console
- https://flic.kr/p/QMVMw Bri Pettis, Dave’s Bike Tools