Publishing API documentation -- Workshop
-
Upload
tom-johnson -
Category
Technology
-
view
789 -
download
8
Transcript of Publishing API documentation -- Workshop
![Page 1: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/1.jpg)
PUBLISHING REST API DOCUMENTATION
BY TOM JOHNSON
IDRATHERBEWRITING.COM
STC Summit 2015 Columbus, Ohio @tomjohnson
![Page 2: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/2.jpg)
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.
![Page 3: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/3.jpg)
1.0 PUBLISHING API DOCS
• Why a course on publishing API docs? What's different?
• Different kinds of APIs
• Platform APIs and REST APIs
![Page 4: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/4.jpg)
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
![Page 5: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/5.jpg)
1.1 BREAKING DOWN API DOC
• API docs have tremendous variety
• No common tooling
• Programableweb.com: A directory of API doc sites
![Page 6: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/6.jpg)
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
![Page 7: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/7.jpg)
BREAKING DOWN API DOCS
a. Guides
b. Tutorials
c. Reference
![Page 8: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/8.jpg)
A. GUIDE DOCS
Common sections in guide docs: API overview, Getting started, Authorization keys, Core concepts, Rate limits, Code samples, Quick reference, Glossary
![Page 9: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/9.jpg)
B. TUTORIAL DOCS
Getting started tutorials, Hello World tutorials, First steps
![Page 10: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/10.jpg)
C. REFERENCE DOCS
Endpoint docs: Resource descriptions, endpoint definitions, methods, parameters, request examples, responses, status codes, code samples
![Page 12: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/12.jpg)
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
![Page 13: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/13.jpg)
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
![Page 15: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/15.jpg)
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);
![Page 17: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/17.jpg)
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/
![Page 18: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/18.jpg)
1.4 GITHUB WIKIS AND MARKDOWN
• Github wikis as
complementary
repositories
• Markdown syntax
• The wiki repository
path
![Page 19: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/19.jpg)
1.4 GITHUB WIKIS AND MARKDOWN
• Treat doc as code
• Working locally
allows you to
leverage other
tools
• Limitations
![Page 20: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/20.jpg)
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
![Page 21: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/21.jpg)
1.5 CUSTOM SCRIPTS FOR HYBRID SOLUTIONS
Source code to JSON
Scripts import JSON
Web CMS pushes JSON into templates
![Page 22: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/22.jpg)
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
![Page 23: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/23.jpg)
1.6 SPEC-GENERATED DOCS (SWAGGER)
- Swagger- RAML- API Blueprint
![Page 24: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/24.jpg)
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
![Page 25: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/25.jpg)
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/
![Page 26: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/26.jpg)
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
![Page 27: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/27.jpg)
1.7 API BLUEPRINT
![Page 28: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/28.jpg)
1.7 API BLUEPRINT
• API Blueprint is another spec
• Sample blueprint
• Parsing the blueprint
![Page 29: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/29.jpg)
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/.
![Page 30: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/30.jpg)
1.8 STATIC SITE GENERATORS (SUCH AS JEKYLL)
• What are static site generators
• Static site generators give you a flexible web platform
![Page 31: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/31.jpg)
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
![Page 32: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/32.jpg)
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
![Page 33: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/33.jpg)
2.0 API DOCUMENTATION-ONLY PUBLISHING PLATFORMS
• Software as a service sites
• No need to spend time developing your own site
![Page 34: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/34.jpg)
2.0 API DOCUMENTATION-ONLY PUBLISHING PLATFORMS
Publish endpoint documentation on readme.io
See the instructions at http://idratherbewriting.com/publishingapidocs2-0
![Page 35: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/35.jpg)
2.1 HELP AUTHORING TOOLS
• Can I use a help authoring tool?
![Page 36: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/36.jpg)
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
![Page 37: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/37.jpg)
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
![Page 39: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/39.jpg)
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
![Page 40: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/40.jpg)
2.2 DESIGN PATTERNS
Several non-patterns with API docs:
• PDF output
• Mobile display
• Comments on pages
• Video tutorials
![Page 41: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/41.jpg)
2.3 PATTERN: STRUCTURE AND TEMPLATES
![Page 42: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/42.jpg)
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
![Page 43: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/43.jpg)
2.4 PATTERN 2: WEBSITE PLATFORM
• One integrated website
• Documentation as product interface
• Integrating information across the entire site
![Page 44: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/44.jpg)
2.5 PATTERN 3: ABUNDANT CODE SAMPLES
• Developers love code examples
• Syntax highlighting
• Code formatting
![Page 45: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/45.jpg)
2.6 PATTERN 4: LONG-ISH PAGES
• Minimize clicking
• Examples of long pages
![Page 46: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/46.jpg)
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?
![Page 47: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/47.jpg)
2.7 PATTERN 5: API INTERACTIVITY
• API explorers
• Novel or actually instructive?
• Dynamically populated code samples with API keys
![Page 48: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/48.jpg)
2.8 CHALLENGING FACTORS
Versioning Translation
Single sourcing PDF
![Page 50: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/50.jpg)
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?
![Page 51: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/51.jpg)
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?
![Page 53: Publishing API documentation -- Workshop](https://reader035.fdocuments.in/reader035/viewer/2022062304/55bea9f2bb61eb010e8b45e7/html5/thumbnails/53.jpg)
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,