Downloaded 18 times
Uploaded byTom Johnson
Publishing API documentation -- Presentation
The document discusses various strategies for publishing API documentation, including different types of documentation like guides, tutorials, and reference docs. It also covers tools for generating documentation from code, hosting platforms, design patterns, and questions to consider regarding developer contributions, security, hosting budgets, and customization needs.
More Related Content
Similar to Publishing API documentation -- Presentation
Publishing API documentation -- Presentation
- 1. {by Tom Johnson idratherbewriting.com Publishingstrategies for API documentation STC Summit 2015 Columbus, Ohio @tomjohnson
- 2. The variety ofAPI docs
- 3. a. Guides b. Tutorials c.Reference Breaking down API docs
- 4.
- 5.
- 6.
- 7. • Resource description •Endpoint • Methods • Parameters • Request example • Response example • Status and error codes • Code samples Reference sections
- 8. If developers willwrite …
- 9. Miredot – Javadoc gen.
- 10.
- 11. Source code to JSON Scriptsimport JSON Web CMS pushes JSON into templates Custom scripts
- 12. Swagger - Swagger - RAML -API Blueprint
- 13. API Blueprint andApiary - Mulesoft - Apigee - Apiary
- 14.
- 15. Static site gen.-- Jekyll Jekyll Docpad Middleman Staticgen.com
- 16.
- 17.
- 18.
- 19.
- 20. API doc designpatterns
- 21. 1. Structure andtemplates
- 22.
- 23. 3. Lots ofcode samples
- 24.
- 25.
- 26.
- 27.
- 28. • Will developersbe 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
- 29.
- 30. Most images arescreenshots 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
- #3 http://www.programmableweb.com/apis/directory
- #5 https://sendgrid.com/docs/User_Guide/index.html
- #6 https://www.parse.com/tutorials
- #7 https://instagram.com/developer/endpoints/relationships/
- #9 https://www.youtube.com/watch?v=EnB8GtPuauw
- #10 http://www.miredot.com/exampledocs/
- #11 https://github.com/ and https://github.com/basecamp/bcx-api/
- #13 http://swagger.io/ and http://editor.swagger.io/
- #14 https://apiary.io/
- #15 http://raml.org/index.html
- #16 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/
- #18 http://readme.io
- #19 https://readthedocs.com/
- #20 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/
- #21 https://flic.kr/p/ssQqiL Earth patterns, flickr. evriel venefice
- #22 https://flic.kr/p/oFD6MM Structure Rafal Zych
- #23 Yelp API doc: https://www.yelp.com/developers/documentation
- #24 https://www.twilio.com/docs/api/rest
- #25 http://documentcloud.github.io/backbone/
- #26 https://dev.twitter.com/rest/tools/console
- #28 https://flic.kr/p/QMVMw Bri Pettis, Dave’s Bike Tools