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.

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

27. 1.7 API BLUEPRINT

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

41. 2.3 PATTERN: STRUCTURE
AND TEMPLATES

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

49. 2.9 TOOLS VERSUS
CONTENT

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?

52. THANKS!
Tom Johnson
idratherbewriting.com
tomjohnson1492@gmail.com

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,