Maintainable API Docs and Other Rainbow Colored Unicorns

MaintainableAPI Docs andOther Rainbow Colored Unicorns
Neil Mansilla
Director, Developer Products

Disclaimer
The views and statements contained herein are my own (Neil Mansilla)
and do not express the views of Mashery, Inc. nor any of its employees,
agents, customers, and associates.
Also, I’m not a Power Point guru, nor am I Anthony Robbins.

Greetings!
Name: Neil Mansilla
Job: Director, Developer Products
Company: Mashery
Email: neil@mashery.com
Web: http://developer.mashery.com
Twitter: @mansillaDEV @mashery

Mashery API Network
Over 100 companies rely on Mashery to manage their API infrastructure
Over 115,000 key-holding developers
Over 30,000 active web and mobile applications
Billions of monthly API calls

Mashery API Network

What does
bad documentation
really say about
your platform?
Your company?

Bad docs say to your users,“I don’t care about you.”
Do your docs elicit any of these responses?
“Why are these docs so awful?”
“Don’t they realize this looks like hell?”
“How in the world am I supposed to understand how this thing works?”
“Do they no longer support this platform?”
“Dude, these guys are bozos.”

A Few Common Pitfalls That Make for Bad Docs
http://www.atarimagazines.com/hi-res/v1n2/davidcrane.php

Technical Overload: Yadda Yadda Yadda
Documentation is a general term for a multiplicity of documents in a chosen mix of media and with a certain collection. Purpose of documentation is the use to support a tool or a process.
Classical documentation is a set of documents printed on paper. Documentation (to document) also refers to the process of providing evidence.
Documentation composure
Documentation may include
written information for any read, projection or technical performing,
data media of any format and for any reproduction,
other content.
Common types of documentation include user guides, white papers, on-line help, quick-reference guides. It is less common to see hard-copy (paper) documentation. Documentation is distributed via websites, software products, and other on-line applications.
[edit] Principles for producing documentation
The following is a list of guides dealing with each specific field and type:
documentation in health care [5]
thesis writing [6], [7], [8]
Further information: Dissertation
papers for academic journal publishing (i.e. Journal of Food Science [9] and Analytical Chemistry [10])
Producing documentation
Technical writers and corporate communicators are professionals whose field and work is documentation. Ideally, technical writers have a background in both the subject matter and also in writing and managing content (information architecture). Technical writers more commonly collaborate with subject matter experts (SMEs), such as engineers, medical professionals, or other types of clients to define and then create content (documentation) that meets the user's needs. Corporate communications includes other types of written documentation that is required for most companies.
[edit] Specializing documentation
Marketing Communications (MarCom) MarCom writers endeavor to convey the company's value proposition through a variety of print, electronic, and social media. This area of corporate writing is often engaged in responding to proposals.
Technical Communication (TechCom) Technical writers document a company's project or service. Technical publication include user guides, installation manuals, and troubleshooting/repair/replace

Too Little a/k/a “Just Enough to Tick You Off”
Method: createSituation(s3, s4, s5)
This method creates a situation
and takes in three parameters.
Method: selectUserByDate(date)
This method selects a user by a date.

Undocumented changes,deprecations.
Changes and deprecations that are not documented
Code samples that no longer work as described

Bad Docs = Angry Developers
http://www.flickr.com/photos/gcarvalho/142922427/

Happy Sys Admin Day!http://www.sysadminday.com

Good API Docs
http://www.flickr.com/photos/scorpio58/4067099731/

Why are API docs so challenging?
Never a top priority(until it’s too late, and even then…)
Initial copy can be very daunting
Audience diversity(can’t please ‘em all)
Dynamic platform = maintenance nightmare

Rethinking APIDocs Design
Rethinking traditional technical documentation design for APIs by asking:
Is there a better way for developers to learn how to use my platform?
What are the pain points developers are experiencing with my current docs?
How can I maintain my API docs more easily?
What kind of CMS will help us be more efficient?

Using Definition Files to Publish Docs
> Traditional API Definition Formats:
WSDL – XML for SOAP
WADL – XML for HTTP/REST
Javadoc – comments in Java

Using Definition Files to Publish Docs
Traditional API Definition Formats:
WSDL – XML for SOAP
WADL – XML for HTTP/REST
Javadoc – comments in Java
> Traditional Doc Generating Tools:
Oxygen XML
XML Spy
Javadoc Tool

New Web Service Definition Formats & Tools

Google Discovery FormatJSON, RESTful APIs
http://code.google.com/apis/discovery/v1/reference.html#resource_discovery
URL Shortener API: https://www.googleapis.com/discovery/v1/apis/urlshortener/v1/rest

Google API Explorer is now open source
Java/GWT
http://code.google.com/p/google-apis-explorer/

Wordnik swagr FormatJSON, RESTful APIs
http://api.wordnik.com/v4/wordList.json

Tool Driven and Interactive Docs
A New Design Pattern: Interactive Documentation

Interactive Docs
A New Design Pattern: Interactive Documentation
Learning by exploration and example
API methods and parameters in plain view
Parameter values, types and limits provided
Ability to make live API calls within documentation
Inbound call, outbound header and payload displayed useful for learning, testing and debugging

Mashery I/O Docs
Inspired by Wordnik and Etsy JSON schemas
Inspired by Wordnik UI/UX for docs
Built prototype in Node.js

Mashery I/O Docs
http://oscon.mansilla.com:3000/usatoday - docs
http://oscon.mansilla.com/os/usatoday.json - schema
"usatoday": {
"name": "USA TODAY",
"baseURL": "api.usatoday.com",
"publicPath": "/open",
"auth": "key",
"keyParam": "api_key”
}

Mashery I/O Docsin Production
http://developer.klout.com
http://developer.alibris.com
http://developer.fanfeedr.com
http://developer.mashery.com

In the spirit of OSCON…
Mashery is open sourcing I/O Docs in Node.js
Will be posted on Github (finishing the docs )
Includes client interface form generator and back-end proxy API call handler (in same stack)
Deploy on your own server in just minutes
Released under MIT License
Plenty of JSON schemas configured with production APIs
Support for RESTful APIs
Support of OAuth (w/HMAC-SHA1), key passed as parameter, MD5/SHA256 signing

Tomorrow, all day, API Hack Day @ Urban Airship HQ
It’s FREE. It’s FUN. It’s FRUN!

I/O Docs Live Demo
Time permitting, pick simple API to build I/O Docs
Sacrifice tweet to @demogods
Go!

Thank you.
Questions (and possibly some answers)
Contact me:
Email - neil@mashery.com
Twitter - @mansillaDEV
http://developer.mashery.com

Browser URLsHere are a list of URLs that I loaded during my presentation:

Maintainable API Docs and Other Rainbow Colored Unicorns

by Mansilladev on Jul 29, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

2 Embeds 33

Statistics

Maintainable API Docs and Other Rainbow Colored Unicorns — Presentation Transcript

http://www.oscon.com	29
http://lanyrd.com	4