KEMBAR78
Publishing strategies for API documentation | PPTX
By Tom Johnson 
www.idratherbewriting.com 
October 15, 2014
More 
info 
needed
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
Single page doc scroll demo
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

  • 1.
    By Tom Johnson www.idratherbewriting.com October 15, 2014
  • 3.
  • 4.
    Presentation by JohnMusser, founder of programmableweb.com, which has directory of 12,000+ APIs
  • 5.
    Says, “The clientwants to find someone who'll emulate Dropbox's developer documentation”
  • 6.
    With APIs, docsare the interface
  • 7.
    Presentation outline NativeAPI 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
  • 9.
    Some basics aboutthe 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.
  • 10.
    The tech writer’sresponsibility
  • 11.
    The concept ofauto-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.
  • 12.
  • 13.
    Javadoc - Commonlyused. - 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 - Commonlyused. - 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.
  • 15.
    Doxygen has GUIfront-end Specify the source directory of your files.
  • 16.
    Pros of in-sourcedocumentation - 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
  • 17.
    Cons of in-sourcedocumentation 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
  • 18.
    Problem 1: Curseof Knowledge A developer who creates the API may assume too much of the audiences’ technical ability. As a result, the descriptions aren’t helpful.
  • 19.
    Problem 2: Nottask-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.
  • 20.
    Problem 3: Lackof 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.
  • 21.
    Problem 4: Doesn’tintegrate 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.
  • 22.
    Problem 5: Givesillusion 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.
  • 23.
    Question: Would mergingauto-doc with regular doc help solve integration and ownership issues?
  • 24.
    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.
  • 25.
    Merge option 2:Abandon tech comm tools for dev tools that use markdown
  • 26.
    “… It remindsme 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
  • 28.
    REST API basics URLs requests return specific data HTTP Request Response
  • 29.
    Responses in JSONor XML Configuration parameters Response in JSON format
  • 30.
    Response Request Thiskind of tutorial lives outside the reference docs.
  • 31.
    cURL calls HTTPrequests are often demonstrated through cURL calls, with different HTTP methods: GET – retrieve POST – edit PUT – create DELETE – remove
  • 32.
    No auto-doc withREST 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
  • 33.
    But REST APIshave some endpoint generator possibilities, with Swagger Generates an endpoint based on values you enter
  • 34.
    And Mashery.io Thisis an API for USA Today.
  • 35.
    Mashery with Klout Doc becomes interactive when you’re signed in.
  • 36.
    Miredot (auto-doc forJava REST) Source code must be Java.
  • 37.
    Sample REST APIdoc sites Many API doc sites are modern looking and awesome. Remember, the API Doc is the product interface, so it has to look good.
  • 38.
  • 39.
    Constant Contact API One seamless website, merging all information on the same site.
  • 40.
    Yelp API Websiteis branded with similar branding as product.
  • 41.
    Dropbox API Cleanand simple look. Minimalist.
  • 42.
    Foursquare API Oftenbegin with Getting Started section, providing a sample “Hello World” tutorial
  • 43.
    Youtube API Lotsof code samples, usually with syntax highlighting and surrounding narrative
  • 44.
    Stripe API Coderequests and responses next to doc
  • 45.
    Twilio API Oneoutput, with tabs to show different languages
  • 46.
    Get Bootstrap API Everything on one page, with dynamic TOC highlighting as you scroll
  • 47.
    Single page docscroll demo
  • 48.
    Twitter API Real-time requests to make the doc interactive.
  • 49.
    Readme.io API authoringtool Says, “Start typing markdown here…” Simple authoring methods, usually Markdown
  • 50.
    Read the Docs Sphinx and Github
  • 51.
    1. Edit onGithub. 2. Commit change. 3. Rebuild view on readthedocs.org.
  • 52.
    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
  • 53.
    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
  • 54.
    Question: How do tech writers make beautiful API doc websites?
  • 55.
    Possible options Cloud-basedsolutions - 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
  • 56.
    How do youmerge worlds? Is it possible to merge tech comm and API doc worlds, or are they too different?
  • 57.
    Import DITA intoWordPress (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)
  • 58.
    Import DITA intoWordPress (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.
  • 59.
    Tom Johnson Idratherbewriting.com tom@idratherbewriting.com @tomjohnson (Twitter)
  • 60.
    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

Editor's Notes

  • #5 ttp://www.slideshare.net/jmusser/ten-reasons-developershateyourapi
  • #12 Source code: http://www.docjar.net/html/api/java/util/Collections.java.html
  • #19 http://online.wsj.com/articles/the-cause-of-bad-writing-1411660188
  • #23 Another source: “Auto-generated documentation that documents each API end-point directly from source code have their place (e.g., its great for team that built the API and its great for a reference document) but hand-crafted quality documentation that walks you through a use case for the API is invaluable. It should tell you about the key end-points that are needed for solving a particular problem and it should provide you with code samples.” https://communities.cisco.com/community/developer/blog/2014/09/03/introducing-devnet-slate
  • #34 Also enunciate http://enunciate.codehaus.org/ and https://github.com/mashery/iodocs
  • #35 http://developer.usatoday.com/io-docs
  • #36 http://developer.klout.com/io-docs
  • #43 https://developer.foursquare.com/start
  • #44 https://developers.google.com/youtube/v3/code_samples/apps-script
  • #45 Also http://ricostacruz.com/jquery.transit/source/ for docco sidebar style Slate patterned after it, and docco
  • #46 http://www.twilio.com/docs/api/rest/conference
  • #47 Article by bokardo: clicking is easier than scrolling: http://bokardo.com/archives/scrolling-easier-clicking/
  • #49 https://dev.twitter.com/rest/reference/get/statuses/user_timeline
  • #54 Splunk’s documentation is an exception to the non-wiki trend.
  • #56 http://blog.iwantmyname.com/2014/05/the-updated-big-list-of-static-website-generators-for-your-site-blog-or-wiki.html https://github.com/skx/static-site-generators/blob/master/README.md http://lwn.net/Articles/541299/