Publishing strategies for API documentation

By Tom Johnson
www.idratherbewriting.com
October 15, 2014

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

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

With APIs, docs are
the interface

Presentation outline
Native API
Docs
REST API
Docs
10 Best
Practices
Topics not covered:
• Writing the technical content
• Interacting with developers
• Learning to read code
• Understanding the different languages
• Commenting on code samples
• Creating getting started, hello world tutorials

Some basics about the API landscape
System B
System A
API
Lots of different types
of APIs – for example:
1. Native APIs that you
download and add
to your project
before compiling.
2. REST APIs that you
access through
HTTP web requests.

The tech writer’s responsibility

The concept of auto-doc
/**
* 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.

Auto-doc output
Javadoc
Doxygen

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.

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.
- Can skin.

Doxygen has GUI front-end
Specify the
source directory
of your files.

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
Continental drift
Doc Src Src
Doc

Cons of in-source documentation
1. Subject to Curse of
Knowledge
2. Not task-focused
3. Suffers from lack of
ownership
4. Doesn’t integrate with
other content
5. Gives illusion of having
real doc

Problem 1: Curse of Knowledge
A developer who
creates the API
may assume too
much of the
audiences’
technical ability.
As a result, the
descriptions
aren’t helpful.

Problem 2: Not task-focused
Auto-doc is feature-based
doc approach.
Task-based doc includes
multiple calls and
workflows in support of
goals. It might make use
of several different
objects and methods
across the reference
doc.

Problem 3: Lack of ownership
Auto-doc is a
stray dog.
Auto-doc is owned
like a stray dog or wiki
is owned. Someone
may contribute some
food or a page
without care for the
whole. Usually there
isn’t a developer
overseeing all the
doc. Tech writers feel
less responsible when
auto-doc is a separate
from their output.

Problem 4: Doesn’t integrate
Auto-doc doesn’t
integrate directly into
a website except as a
link from your other
web pages. Like a
HAT-produced
webhelp file, the
auto-doc is its own
little website.

Problem 5: Gives illusion of real doc
“… auto-generated
documentation is worse than
useless: it lets maintainers fool
themselves into thinking they
have documentation, thus
putting off actually writing good
reference by hand. If you don’t
have documentation just admit
to it. Maybe a volunteer will
offer to write some! But don’t
lie and give me that auto-documentation
crap”. – Jacob
Kaplan Moss
Looks real but
isn’t.

Question: Would
merging auto-doc
with regular doc
help solve
integration and
ownership issues?

Merge option 1: Leverage DITA to pull
source doc into tech comm tools
You run the Docfacto
DITA doclet inside
Eclipse just like
Javadoc, but you
select a custom DITA
Doclet. Files get
converted to
reference topic
types. With Docfacto
Links, you can add
links to and from in-source
files.

Merge option 2: Abandon tech comm
tools for dev tools that use markdown

“… It reminds me of back in the day when I
was a photographer. So many of my
colleagues were wrapped up in the
technology, they forgot the original purpose
was to create a photograph. Same with
document generators. We are debating
whether it's better to generate docs from
source comments than an alternative. My
point is that this debate is a red herring. It's
not where you put the information, it's the
quality of the information.”
– Doug Schwartz

REST API basics
URLs requests return specific data HTTP Request
Response

Responses in JSON or XML
Configuration
parameters
Response in JSON format

Response
Request
This kind of tutorial
lives outside the
reference docs.

cURL calls
HTTP requests are often demonstrated through
cURL calls, with different HTTP methods:
GET – retrieve
POST – edit
PUT – create
DELETE – remove

No auto-doc with REST APIs because
source language varies so much
“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

But REST APIs have some endpoint
generator possibilities, with Swagger
Generates an endpoint
based on values you
enter

And Mashery.io
This is an API for
USA Today.

Mashery with Klout
Doc becomes
interactive
when you’re
signed in.

Miredot (auto-doc for Java REST)
Source code
must be Java.

Sample REST API doc sites
Many API doc sites
are modern looking
and awesome.
Remember, the API
Doc is the product
interface, so it has
to look good.

Programmableweb.com: API Directory
12,000 + APIs

Constant Contact API
One seamless website,
merging all information
on the same site.

Yelp API Website is
branded with
similar branding
as product.

Dropbox API
Clean and simple
look. Minimalist.

Foursquare API
Often begin with
Getting Started section,
providing a sample
“Hello World” tutorial

Youtube API
Lots of code samples,
usually with syntax
highlighting and
surrounding narrative

Stripe API
Code requests
and responses
next to doc

Twilio API
One output, with
tabs to show
different
languages

Get Bootstrap API
Everything on one
page, with dynamic
TOC highlighting as
you scroll

Twitter API
Real-time
requests to
make the doc
interactive.

Readme.io API authoring tool
Says, “Start typing
markdown here…”
Simple authoring
methods, usually
Markdown

Read the Docs
Sphinx and
Github

1. Edit on Github.
2. Commit change.
3. Rebuild view on
readthedocs.org.

10 Trends
1. One seamless website
2. Product-branding
3. Minimalism
4. Getting started section
5. Emphasis on code samples
6. Side-by-side code
7. jQuery tabs
8. Single-page doc
9. Real-time requests/demo
10.Markdown

10 non-trends
1. PDF output
2. Collapsible sections
3. Short pages
4. Multiple outputs of content for different audiences
5. DITA or XML authoring models
6. EPUB and mobile formats
7. Comments on pages
8. Wikis
9. Tripane webhelp files
10. Video tutorials

Question: How do
tech writers make
beautiful API doc
websites?

Possible options
Cloud-based solutions
- Readme.io
- Miredot
- Apiary
- API Blueprint
- 3scale.net
- Turnapi
- Github
Static site generators
- Slate
- Wintersmith
- Nanoc
- Jekyll
- Pico CMS
- Sphinx
- Fixie docs
Doc. generators
- Enunciate
- Docco
- Dexy
- Swagger
- Mashery I/O docs
- RAML
DITA-based
- WordPress
Wikis
- Mediawiki
- Ponydocs
- Confluence

How do you merge worlds?
Is it possible to
merge tech comm
and API doc worlds,
or are they too
different?

Import DITA into WordPress (Pros)
Pros
- Easy to build and theme a beautiful site.
- Create a network of sites controlled from a single point.
- Imports DITA flawlessly.
- Include additional functionality (e.g., forums, Q&A).
- Leverage existing plugins (auto-toc, jQuery menus, live
search).
- Easily hire out branding and code development.
- Works with a lot of different systems (30,000 + plugins).
- Dynamically serve conditional content to users.
- Allow threaded comments (SME review, user feedback).
- Include other content outside of doc (mktg., kb articles)
- Much better analytics (e.g., see search queries on dashbrd)

Import DITA into WordPress (Cons)
Cons
- Database model is slower than static files.
- Import process isn’t a one-click job.
- Requires MySQL, PHP, and Apache architecture.
- May be problematic to integrate authentication with
another system (e.g., Salesforce).
- Regularly importing static files into a dynamic system may
be subverting the fundamental design of WordPress.
- May not be robust enough for massive doc projects.

Tom Johnson
Idratherbewriting.com
tom@idratherbewriting.com
@tomjohnson (Twitter)

Image Credits
• Slide 2: Mars, once. By Kevin Dooley. http://bit.ly/ZFYI0T
• Slide 4: 10 Reasons Developers Hate Your API (and what to do about it). By John Musser.
Slideshare. http://slidesha.re/1pnnDRf
• Slide 9. Spinning gears. By Brent 2.0. Flickr. http://bit.ly/1DexWM0
• Slide 10. Lolcat Generator: Can haz posters? http://bighugelabs.com/lolcat.php
• Slide 11. Code sample pulled from
http://www.docjar.net/html/api/java/util/Collections.java.html.
• Slide 16. Continental Drift. Wikipedia. http://en.wikipedia.org/wiki/Continental_drift
• Slide 17: Biodiversity fail. By Martin Sharma. Flickr. http://bit.ly/1CodnKM
• Slide 18. The Source of Bad Writing. Wall Street Journal. http://online.wsj.com/articles/the-cause-
of-bad-writing-1411660188
• Slide 19. Stray dog. By Jose Javier Perez Arenas. Flickr. http://bit.ly/1wau5NK
• Slide 22. The false. By Cristopher Cotrell. Flickr. http://bit.ly/1F1et36. Quote from Jacob
Kaplan Moss here: http://jacobian.org/writing/what-to-write/
• Slide 23 and 54. Finger face with question. By Tsahi Levent-Levi. http://bit.ly/1sWdnln
• Slide 32. Kin Lane, apievangelist.com. http://apievangelist.com/2012/03/08/automated-documentation-
for-rest-apis/
• Slide 37. Catwoman. http://bit.ly/11qDsNU
• Slide 56. Nasa, new eyes: Butterfly. http://bit.ly/1u7ANzE

Publishing strategies for API documentation

More Related Content

What's hot

Viewers also liked

Similar to Publishing strategies for API documentation

More from Tom Johnson

Recently uploaded

Publishing strategies for API documentation

Editor's Notes