publishing api documentation -- workshop
TRANSCRIPT
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.com: 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 …
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)/** * 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
Browse the Miredot source code: https://github.com/Qmino/miredot-petstore/blob/master/src/main/java/com/qmino/miredot/petstore/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/developercloud/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
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
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?
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,