SlideShare a Scribd company logo

Publishing API documentation -- Workshop

•Download as PPTX, PDF•
•
Tom Johnson
Tom Johnson

These slides are from the REST API documentation workshop that I gave at the STC Summit 2015. For more details, see http://idratherbewriting.com/publishingapidocs.

Related slideshows

API workshop: Deep dive into Java
API workshop: Deep dive into JavaAPI workshop: Deep dive into Java
API workshop: Deep dive into Java
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)
 
Writing code samples for API/SDK documentation
Writing code samples for API/SDK documentationWriting code samples for API/SDK documentation
Writing code samples for API/SDK documentation
 
1 of 53
PUBLISHING REST API DOCUMENTATION BY TOM JOHNSON IDRATHERBEWRITING.COM STC Summit 2015  Columbus, Ohio  @tomjohnson
WORKSHOP CONVENTIONS • Access the workshop course at http://idratherberwriting.com/publishingapidocs • 1.1 Numbers in slide headings refers to the place in the course. •  This icon indicates an activity you’re supposed to do. • If you get lost, read the course page.
1.0 PUBLISHING API DOCS • Why a course on publishing API docs? What's different? • Different kinds of APIs • Platform APIs and REST APIs
1.0 PUBLISHING API DOCS REST APIs are taking off in a huge way Publishing is one value tech writers can add to highly technical content
1.1 BREAKING DOWN API DOC • API docs have tremendous variety • No common tooling • Programableweb.co m: A directory of API doc sites
1.1 BREAKING DOWN API DOC  Browse 5 different API doc sites from the list here: http://idratherbewriting.com/publishingapidocs1-1 Identifying similar patterns and structures
BREAKING DOWN API DOCS a. Guides b. Tutorials c. Reference
A. GUIDE DOCS Common sections in guide docs: API overview, Getting started, Authorization keys, Core concepts, Rate limits, Code samples, Quick reference, Glossary
B. TUTORIAL DOCS Getting started tutorials, Hello World tutorials, First steps
C. REFERENCE DOCS Endpoint docs: Resource descriptions, endpoint definitions, methods, parameters, request examples, responses, status codes, code samples
1.2 IF DEVELOPERS WILL WRITE …
1.2 IF DEVELOPERS WILL WRITE … Pros of having developers write: • Avoids documentation drift • Allows the person who creates the code (and so best understands it) to also document it
1.2 IF DEVELOPERS WILL WRITE … Cons of having developers write: • The curse of knowledge • Not task-focused • Output doesn't integrate with user guide • Gives illusion of having complete doc
1.3 GENERATING REFERENCE DOCS FROM SOURCE (MIREDOT)
1.3 GENERATING REFERENCE DOCS FROM SOURCE (MIREDOT) /** * Update category name and description. Cannot be used to edit products in this category. * * @param categoryId The id of the category that will be updated * @param category The category details * @summary Update category name and description */ @PUT @Path("/category/{id}") @Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) public void updateCategory(@PathParam("id") Long categoryId, Category category);
1.3 GENERATING REFERENCE DOCS FROM SOURCE (MIREDOT)
1.3 GENERATING REFERENCE DOCS FROM SOURCE  Browse the Miredot source code: https://github.com/Qmino/miredot- petstore/blob/master/src/main/java/com/qmino/miredot/pets tore/service/CatalogService.java  Browse the Miredot sample output: http://miredot.com/exampledocs/
1.4 GITHUB WIKIS AND MARKDOWN • Github wikis as complementary repositories • Markdown syntax • The wiki repository path
1.4 GITHUB WIKIS AND MARKDOWN • Treat doc as code • Working locally allows you to leverage other tools • Limitations
1.4 GITHUB WIKIS AND MARKDOWN See the instructions at http://idratherbewriting.com/publishingapidocs1-4/  a. Publish a sample file on Github  b. Save the Github repository locally  c. Make a change locally and commit it to the repository
1.5 CUSTOM SCRIPTS FOR HYBRID SOLUTIONS Source code to JSON Scripts import JSON Web CMS pushes JSON into templates
1.5 CUSTOM SCRIPTS FOR HYBRID SOLUTIONS • Solution at Badgeville • Use scripts to generate JSON from source code • Import the JSON into your web CMS • Developing custom solutions
1.6 SPEC-GENERATED DOCS (SWAGGER) - Swagger - RAML - API Blueprint
1.6 SPEC-GENERATED DOCS (SWAGGER) • Specs replace program-specific doc blocks • Sorting out the Swagger components - Swagger spec - Swagger editor - Swagger UI • Swagger libraries • Limitations with spec-driven documentation
1.6 SPEC-GENERATED DOCS (SWAGGER)  Check out some Swagger implementations: • Reverb: https://reverb.com/swagger#!/accounts • VocaDB: http://vocadb.net/swagger/ui/index • Watson Developer Cloud: http://www.ibm.com/smarterplanet/us/en/ibmwatson/develope rcloud/apis/
1.6 SPEC-GENERATED DOCS (SWAGGER) See instructions at http://idratherbewriting.com/publishingapidocs1-6  a. Create a Swagger spec file  b. Set Up the Swagger UI  c. Upload the Files to a Web Host
1.7 API BLUEPRINT
1.7 API BLUEPRINT • API Blueprint is another spec • Sample blueprint • Parsing the blueprint
1.7 API BLUEPRINT  Create a sample HTML output using API Blueprint and Apiary  a. Create a new Apiary project  b. Interact with the API on Apiary See instructions at http://idratherbewriting.com/publishingapidocs1-7/.
1.8 STATIC SITE GENERATORS (SUCH AS JEKYLL) • What are static site generators • Static site generators give you a flexible web platform
1.8 STATIC SITE GENERATORS (SUCH AS JEKYLL)  Publish the surfreport in a Jekyll theme on CloudCannon  Follow the instructions here: http://idratherbewriting.com/publishingapidocs1-8
1.9 CUSTOM UX SOLUTIONS • Beautiful API doc sites require front- end design skills • When it makes sense to partner with UX • Web platform languages
2.0 API DOCUMENTATION-ONLY PUBLISHING PLATFORMS • Software as a service sites • No need to spend time developing your own site
2.0 API DOCUMENTATION-ONLY PUBLISHING PLATFORMS  Publish endpoint documentation on readme.io  See the instructions at http://idratherbewriting.com/publishingapidocs2-0
2.1 HELP AUTHORING TOOLS • Can I use a help authoring tool?
2.1 HELP AUTHORING TOOLS • Pros of using a help authoring tool • Comfortable authoring environment for writers. • Integrates reference information with guides and tutorials. • Handles the toughest tech comm scenarios • HATs reinforce the fact that API doc is more than endpoints
2.1 HELP AUTHORING TOOLS • Cons of using a help authoring tool • Most HATs don't run on Macs • Dated UI won't help sell the product • Doesn't integrate with other site components • Removes authoring capability from developers
2.2 DESIGN PATTERNS • Design patterns are recurring design themes
2.2 DESIGN PATTERNS Several design patterns with API docs 1. Structure and templates 2. Website platform 3. Abundant code examples 4. Longish pages 5. Interactive API explorers
2.2 DESIGN PATTERNS Several non-patterns with API docs: • PDF output • Mobile display • Comments on pages • Video tutorials
2.3 PATTERN: STRUCTURE AND TEMPLATES
2.3 PATTERN 1: STRUCTURE AND TEMPLATES • Using a template • Pushing values into more stylized outputs • Templates in Jekyll • Templates make it easy to change display globally
2.4 PATTERN 2: WEBSITE PLATFORM • One integrated website • Documentation as product interface • Integrating information across the entire site
2.5 PATTERN 3: ABUNDANT CODE SAMPLES • Developers love code examples • Syntax highlighting • Code formatting
2.6 PATTERN 4: LONG-ISH PAGES • Minimize clicking • Examples of long pages
2.6 PATTERN 4: LONG-ISH PAGES Why long pages? • Provides the big picture • Many platforms lack search • Everything is at your fingertips • Today's navigation controls are sophisticated Is it a best practice to make long pages?
2.7 PATTERN 5: API INTERACTIVITY • API explorers • Novel or actually instructive? • Dynamically populated code samples with API keys
2.8 CHALLENGING FACTORS Versioning Translation Single sourcing PDF
2.9 TOOLS VERSUS CONTENT
3.0 CONCLUSION Questions to consider • 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 service?
3.0 CONCLUSION Questions to consider • How many endpoints do you have to document? • Should you push documentation from the source into your documentation • Can 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?
THANKS! Tom Johnson idratherbewriting.com tomjohnson1492@gmail.com
IMAGE CREDITS Most images are screenshots linked to a webpage, but some are from Flickr. 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,

More Related Content

Publishing API documentation -- Workshop

  • 1. PUBLISHING REST API DOCUMENTATION BY TOM JOHNSON IDRATHERBEWRITING.COM STC Summit 2015  Columbus, Ohio  @tomjohnson
  • 2. WORKSHOP CONVENTIONS • Access the workshop course at http://idratherberwriting.com/publishingapidocs • 1.1 Numbers in slide headings refers to the place in the course. •  This icon indicates an activity you’re supposed to do. • If you get lost, read the course page.
  • 3. 1.0 PUBLISHING API DOCS • Why a course on publishing API docs? What's different? • Different kinds of APIs • Platform APIs and REST APIs
  • 4. 1.0 PUBLISHING API DOCS REST APIs are taking off in a huge way Publishing is one value tech writers can add to highly technical content
  • 5. 1.1 BREAKING DOWN API DOC • API docs have tremendous variety • No common tooling • Programableweb.co m: A directory of API doc sites
  • 6. 1.1 BREAKING DOWN API DOC  Browse 5 different API doc sites from the list here: http://idratherbewriting.com/publishingapidocs1-1 Identifying similar patterns and structures
  • 7. BREAKING DOWN API DOCS a. Guides b. Tutorials c. Reference
  • 8. A. GUIDE DOCS Common sections in guide docs: API overview, Getting started, Authorization keys, Core concepts, Rate limits, Code samples, Quick reference, Glossary
  • 9. B. TUTORIAL DOCS Getting started tutorials, Hello World tutorials, First steps
  • 10. C. REFERENCE DOCS Endpoint docs: Resource descriptions, endpoint definitions, methods, parameters, request examples, responses, status codes, code samples
  • 11. 1.2 IF DEVELOPERS WILL WRITE …
  • 12. 1.2 IF DEVELOPERS WILL WRITE … Pros of having developers write: • Avoids documentation drift • Allows the person who creates the code (and so best understands it) to also document it
  • 13. 1.2 IF DEVELOPERS WILL WRITE … Cons of having developers write: • The curse of knowledge • Not task-focused • Output doesn't integrate with user guide • Gives illusion of having complete doc
  • 14. 1.3 GENERATING REFERENCE DOCS FROM SOURCE (MIREDOT)
  • 15. 1.3 GENERATING REFERENCE DOCS FROM SOURCE (MIREDOT) /** * Update category name and description. Cannot be used to edit products in this category. * * @param categoryId The id of the category that will be updated * @param category The category details * @summary Update category name and description */ @PUT @Path("/category/{id}") @Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) public void updateCategory(@PathParam("id") Long categoryId, Category category);
  • 16. 1.3 GENERATING REFERENCE DOCS FROM SOURCE (MIREDOT)
  • 17. 1.3 GENERATING REFERENCE DOCS FROM SOURCE  Browse the Miredot source code: https://github.com/Qmino/miredot- petstore/blob/master/src/main/java/com/qmino/miredot/pets tore/service/CatalogService.java  Browse the Miredot sample output: http://miredot.com/exampledocs/
  • 18. 1.4 GITHUB WIKIS AND MARKDOWN • Github wikis as complementary repositories • Markdown syntax • The wiki repository path
  • 19. 1.4 GITHUB WIKIS AND MARKDOWN • Treat doc as code • Working locally allows you to leverage other tools • Limitations
  • 20. 1.4 GITHUB WIKIS AND MARKDOWN See the instructions at http://idratherbewriting.com/publishingapidocs1-4/  a. Publish a sample file on Github  b. Save the Github repository locally  c. Make a change locally and commit it to the repository
  • 21. 1.5 CUSTOM SCRIPTS FOR HYBRID SOLUTIONS Source code to JSON Scripts import JSON Web CMS pushes JSON into templates
  • 22. 1.5 CUSTOM SCRIPTS FOR HYBRID SOLUTIONS • Solution at Badgeville • Use scripts to generate JSON from source code • Import the JSON into your web CMS • Developing custom solutions
  • 23. 1.6 SPEC-GENERATED DOCS (SWAGGER) - Swagger - RAML - API Blueprint
  • 24. 1.6 SPEC-GENERATED DOCS (SWAGGER) • Specs replace program-specific doc blocks • Sorting out the Swagger components - Swagger spec - Swagger editor - Swagger UI • Swagger libraries • Limitations with spec-driven documentation
  • 25. 1.6 SPEC-GENERATED DOCS (SWAGGER)  Check out some Swagger implementations: • Reverb: https://reverb.com/swagger#!/accounts • VocaDB: http://vocadb.net/swagger/ui/index • Watson Developer Cloud: http://www.ibm.com/smarterplanet/us/en/ibmwatson/develope rcloud/apis/
  • 26. 1.6 SPEC-GENERATED DOCS (SWAGGER) See instructions at http://idratherbewriting.com/publishingapidocs1-6  a. Create a Swagger spec file  b. Set Up the Swagger UI  c. Upload the Files to a Web Host
  • 28. 1.7 API BLUEPRINT • API Blueprint is another spec • Sample blueprint • Parsing the blueprint
  • 29. 1.7 API BLUEPRINT  Create a sample HTML output using API Blueprint and Apiary  a. Create a new Apiary project  b. Interact with the API on Apiary See instructions at http://idratherbewriting.com/publishingapidocs1-7/.
  • 30. 1.8 STATIC SITE GENERATORS (SUCH AS JEKYLL) • What are static site generators • Static site generators give you a flexible web platform
  • 31. 1.8 STATIC SITE GENERATORS (SUCH AS JEKYLL)  Publish the surfreport in a Jekyll theme on CloudCannon  Follow the instructions here: http://idratherbewriting.com/publishingapidocs1-8
  • 32. 1.9 CUSTOM UX SOLUTIONS • Beautiful API doc sites require front- end design skills • When it makes sense to partner with UX • Web platform languages
  • 33. 2.0 API DOCUMENTATION-ONLY PUBLISHING PLATFORMS • Software as a service sites • No need to spend time developing your own site
  • 34. 2.0 API DOCUMENTATION-ONLY PUBLISHING PLATFORMS  Publish endpoint documentation on readme.io  See the instructions at http://idratherbewriting.com/publishingapidocs2-0
  • 35. 2.1 HELP AUTHORING TOOLS • Can I use a help authoring tool?
  • 36. 2.1 HELP AUTHORING TOOLS • Pros of using a help authoring tool • Comfortable authoring environment for writers. • Integrates reference information with guides and tutorials. • Handles the toughest tech comm scenarios • HATs reinforce the fact that API doc is more than endpoints
  • 37. 2.1 HELP AUTHORING TOOLS • Cons of using a help authoring tool • Most HATs don't run on Macs • Dated UI won't help sell the product • Doesn't integrate with other site components • Removes authoring capability from developers
  • 38. 2.2 DESIGN PATTERNS • Design patterns are recurring design themes
  • 39. 2.2 DESIGN PATTERNS Several design patterns with API docs 1. Structure and templates 2. Website platform 3. Abundant code examples 4. Longish pages 5. Interactive API explorers
  • 40. 2.2 DESIGN PATTERNS Several non-patterns with API docs: • PDF output • Mobile display • Comments on pages • Video tutorials
  • 42. 2.3 PATTERN 1: STRUCTURE AND TEMPLATES • Using a template • Pushing values into more stylized outputs • Templates in Jekyll • Templates make it easy to change display globally
  • 43. 2.4 PATTERN 2: WEBSITE PLATFORM • One integrated website • Documentation as product interface • Integrating information across the entire site
  • 44. 2.5 PATTERN 3: ABUNDANT CODE SAMPLES • Developers love code examples • Syntax highlighting • Code formatting
  • 45. 2.6 PATTERN 4: LONG-ISH PAGES • Minimize clicking • Examples of long pages
  • 46. 2.6 PATTERN 4: LONG-ISH PAGES Why long pages? • Provides the big picture • Many platforms lack search • Everything is at your fingertips • Today's navigation controls are sophisticated Is it a best practice to make long pages?
  • 47. 2.7 PATTERN 5: API INTERACTIVITY • API explorers • Novel or actually instructive? • Dynamically populated code samples with API keys
  • 48. 2.8 CHALLENGING FACTORS Versioning Translation Single sourcing PDF
  • 50. 3.0 CONCLUSION Questions to consider • 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 service?
  • 51. 3.0 CONCLUSION Questions to consider • How many endpoints do you have to document? • Should you push documentation from the source into your documentation • Can 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?
  • 53. IMAGE CREDITS Most images are screenshots linked to a webpage, but some are from Flickr. 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,