This is a presentation I gave to the Southwestern Ontario STC chapter on API documentation on Feb 2, 2015. For more details, see my blog at http://idratherbewriting.com. You can listen to the recorded presentation here: http://youtu.be/I8rGe2w1sAo.

1. Survival Strategies for API
Documentation
By Tom Johnson
www.idratherbewriting.com
Feb 2, 2015
Southwestern Ontario STC Chapter Webinar

2. "Complete and accurate documentation" is most important factor in APIs, according to
a survey by @programmableweb. 250 respondents.
Important factors in API doc

3. Presentation by John Musser, founder of programmableweb.com,
which has directory of 12,000+ APIs

5. Says, “The client wants to
find someone who'll emulate
Dropbox's developer
documentation”

6. Docs are how users
navigate an API product.
With APIs, docs are the interface

7. More
info
needed

8. About me
• Started doing API/SDK documentation
a couple of years ago.
• Am still learning a ton, but enjoy
this type of documentation a lot.
• English major / writing background.
Not a programmer, but I do like code.
• Blog and podcast at
idratherbewriting.com
Disclaimer:
There’s a lot
of things I
simply do not
know.

9. Some basics about the API landscape
System B
System A
An API is an interface
between two systems.
Lots of different types
of APIs – for example:
1. Platform APIs that
you download and
add to your project
before compiling.
2. REST APIs that you
access through
HTTP web requests.

10. SDK versus API
• API (application programming interface): An
interface that provides endpoints, classes, or
other functions.
• SDK (software development kit): A set of
implementation tools to make it easier to work
with an API.
SDK example: A JavaScript SDK that allows you to
work with a particular REST API using JavaScript
syntax as your implementation format.

11. Reference and User Guides
API docs usually
have at least two
deliverables.

12. Auto-doc with Platform APIs
/**
* Reverses the order of the elements in the specified list.<p>
*
* This method runs in linear time.
*
*
* @param list the list whose elements are to be reversed.
* @throws UnsupportedOperationException if the specified list or
* its list-iterator does not support the <tt>set</tt>
operation.
*/
public static void reverse(List<?> list) {
int size = list.size()
if (size < REVERSE_THRESHOLD || list instanceof
RandomAccess) {
for (int i=0, mid=size>>1, j=size-1; i<mid;
i++, j--)
swap(list, i, j);
} else {
…
Add documentation in the
source code, structuring it with
specific syntax that a
documentation generator can
read.

13. Comments get rendered into Javadoc
- Commonly used.
- Works only for Java.
- Run it from your IDE.
- Automate into builds.
- Explore other doclets.
- Has frame-based -
output.
- Can skin with CSS.
- Looks professional.

14. Doxygen
- Commonly used.
- Works with Java, C++,
C#, and others.
- Has easy front-end GUI.
- Point it at your source
files.
- Automate into builds.
- Can include non-source
files (Markdown).
- Frame-based output.
- Skinnable.

15. Good example of source-gen. doc
https://www.dropbox.com/developers/core
Each language
uses a doc
generator for
that language.
https://www.dropbox.com/developers/core

16. Pros of in-source documentation
- Avoids documentation
drift
- Allows the person who
creates the code (and
so best understands it)
to also document it
- Includes tooltips when
others incorporate the
library into their
projects
- Integrates into
developer’s IDE
Doc
SrcDoc Src
Continental drift

17. Pros/cons with Platform APIs
Pros
Performance: Performance is faster. (REST APIs struggle
with latency for web calls.)
Security: More secure.
Cons
Language coverage: Harder for devs to create APIs for
each language (C++, Java, etc.). As prog. languages
proliferate, it’s harder to keep up.
Upgrades: Once clients install, it’s hard to encourage
upgrades to latest versions.

19. REST API basics
URLs requests return specific data HTTP Request
Response

20. Responses in JSON or XML
Configuration
parameters
ResponseinJSONformat

21. Add parameters to endpoints
https://api.flickr.com/services/rest/?method=flic
kr.activity.userPhotos&api_key=1712c56e30dbad
5ef736245cda0d1cb9&per_page=10&format=js
on&nojsoncallback=1
Knowing what parameters
you can include with an
endpoint is a huge part of the
REST API documentation.

22. cURL calls
HTTP requests are often demonstrated through
cURL calls, with different HTTP methods:
GET – retrieve
POST – edit
PUT – create
DELETE – remove
You can use a command line to pass cURL calls, and
you can specify different HTTP methods.
Many sample REST calls
are demonstrated in cURL.

23. Flickr Example: Get gallery photos

24. Get flickr photo gallery
Endpoint:
flickr.galleries.getPhotos
Endpoint with values:
https://api.flickr.com/services/rest/?method=fl
ickr.galleries.getPhotos&api_key=c962d7440cbbf3
81785c09999ba8032e&gallery_id=66911286-
72157647277042064&format=json&nojsoncallback=1
Response:
{
"score": 92.2655186160279,
"scoreDelta": {
"dayChange": 0.00044535591406713593,
… }

25. Flickr Response

26. $("#flickr").append('<img src="https://farm' +
farmId + '.staticflickr.com/' + serverId + '/'
+ id + '_' + secret + '.jpg"/>');
API reference docs don’t
tell you how to actually do
a real task. To construct
the img URL, you need to
combine 4 different parts
from the response.

27. Flickr Result

28. More details on the API calls
Go here for details:
http://bit.ly/restapiexamples

29. Convert your help into an API
The Jekyll Pages
API plugin
converts your
Jekyll pages into a
JSON file.
http://idratherbewriting.com/wp-content/apidemos/docasapi/api/v1/pages.json

30. Call the API
<script>
var url = "http://idratherbewriting.com/wp-
content/apidemos/docasapi/api/v1/pages.json";
$.getJSON(url, function(data) {
console.log(data);
$.each(data.entries, function(i, page) {
if (page.url == "/wp-content/apidemos/docasapi/mynameistom/") {
$("#tomsmyname").append(page.body);
}
});
});
</script>
<div id="tomsmyname"></div>

31. Sample Responses
http://idratherbewriting.com/wp-content/apidemos/sampledocapicall.html

32. More details
http://bit.ly/jekylljsonapi

33. With REST APIs, auto-doc not as
common b/c source lang. varies
“The beauty of Web APIs is that they can be written in
whatever language you like and in whatever manner you
like. As long as when an HTTP request comes in, the proper
HTTP response goes out, it doesn't matter how it actually
happens on the server. But this very flexibility makes
automated documentation nearly impossible, since there's
no standard mapping between what an API request is and
what the code is that generates its response.”
-- Kin Lane, APIevangelist.com

34. Autodoc possibility: Swagger spec

35. RAML (REST API modeling language)

36. Swagger UI can parse the Swagger
syntax and render an output
Generates an endpoint
based on values you
enter

37. Mashery with Klout
Doc becomes
interactive
when you’re
signed in.
http://developer.klout.com/io-docs

38. Mashery.io
This is an API for
USA Today. The
Swagger and
RAML parsers
essentially create
an API explorer
experience with
some doc mixed
in.
http://developer.usatoday.com/io-docs

39. Swagger spec can be in source code or
in separate YML file
• Swagger spec syntax can be separate yml file
or integrated in code using a specific Swagger
library
• Swagger has various libraries for different
languages.
• Swagger spec is different from Swagger UI
• RAML is a competing spec to Swagger

40. Information survey on my blog
• 42 respondents working in API documentation
• Many people polled from API Documentation
group on Linkedin + blogosphere

41. Types of APIs that writers document
0%
10%
20%
30%
40%
50%
60%
70%
80%
90%

42. Are you automating REST API docs?
No Yes N/A
0%
10%
20%
30%
40%
50%
60%
70%
Percent

43. How are you automating REST API
docs?
• - custom scripts
• - custom tooling
• - homegrown framework
• - homegrown Python scripts
• - custom tooling
• - Swagger
• - Swagger
• - Swagger
• - Corilla.co
• - code responses auto-generated
• - some code samples auto-generated

44. Authoring tools used by API doc
writers
0
10
20
30
40
50
60
70
80

45. Do you test out the API calls used in
your doc yourself?
Yes No Sometimes
0%
10%
20%
30%
40%
50%
60%

46. What IDE do you use?
Eclipse None Visual Studio IntelliJ IDEA Xcode Other
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%

47. Most common programming
languages tech writers know
0
5
10
15
20
25

48. Do developers write the initial API
documentation in the source code?
Yes No Sometimes
28%
29%
30%
31%
32%
33%
34%
35%
36%
37%

49. Do you write doc by looking in the
source code?
Yes No
0%
10%
20%
30%
40%
50%
60%
70%

50. How do you access the source code?
Git Perforce No access to
code
SVN Other Mercurial
0%
5%
10%
15%
20%
25%
30%
35%
40%

51. Most difficult part of API doc?
Understand
code
Get info from
engineers
Create non-ref
docs
Understand
audience
Identify
dependencies
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%
Percent

52. How did you learn what you needed to
know?
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%

53. Takeaways from survey
• Java, Eclipse, Git are popular
• Become familiar with getting info from both
source code and developers
• Become a self-learner but also interact heavily
with engineers
• REST APIs are by far most common
• Automating REST API doc isn’t all that
common

54. Programmableweb.com: API Directory
12,000 + web APIs

55. What design
trends or patterns
do we see among
popular API doc
sites?

56. Stripe API
Code responses
next to doc.
https://stripe.com/docs/api

57. Single page scroll w/ TOC highlight
Third column to show
responses or code samples.
http://crimson-cormorant.cloudvent.net/

58. Jekyll API doc theme from
CloudCannon

59. Bootstrap scollspy demo

60. Yelp API
One seamless website
matching product
branding.
http://www.yelp.com/developers/documentation

61. Twilio API
One output, with
nav tabs to show
different
languages

62. Twitter API
Interactive, real-
time requests
based on your
auth key

63. Dynamically
inserted API keys
into code samples.
https://stripe.com/docs/api

64. Foursquare API
Often begin with
Getting Started section,
providing a sample
“Hello World” tutorial
https://developer.foursquare.com/start

65. Youtube API
Lots of code samples,
usually with syntax
highlighting and
surrounding commentary.
https://developers.google.com/youtube/v3/code_samples/apps-script

66. 8 design trends with API doc
1. Third column to show responses & code
2. Single page scroll with scrollspy TOC highlight
and floating sidebar
3. Seamless website matching product branding
4. Nav tabs to show different code samples
5. Code syntax highlighting
6. Hello World getting started section
7. Interactive, personalized API explorer
8. Static site generators that process Markdown
syntax

67. Some non-trends
1. PDF output
2. Short pages
3. Multiple (highly duplicate) outputs of content
for different audiences
4. DITA or XML authoring models
5. EPUB formats
6. Comments on pages
7. Wikis
8. Video tutorials

68. Slides + recording + code samples are
freely downloadable

69. Tom Johnson
http://idratherbewriting.com
@tomjohnson

70. Image credits
• slide 2: "API consumers want reliability, documentation and community."
Programmableweb.com. http://bit.ly/progwebsurvey
• slide 3: “10 Reasons Developers Hate Your API” (and what to do about it).
By John Musser. Slideshare. http://slidesha.re/1pnnDRf
• slide 4: Mars, once. By Kevin Dooley. http://bit.ly/ZFYI0T
• slide 15: Spinning gears. By Brent 2.0. Flickr. http://bit.ly/1DexWM0
• slide 21: Continental Drift. Wikipedia.
http://en.wikipedia.org/wiki/Continental_drift
• slide 24: Programmableweb Research Center.
http://www.programmableweb.com/api-research