MaintainableAPI Docs andOther Rainbow Colored Unicorns<br />Neil Mansilla<br />Director, Developer Products<br />
Disclaimer<br />The views and statements contained herein are my own (Neil Mansilla)<br />and do not express the views of ...
Greetings!<br /><ul><li>Name: Neil Mansilla
Job: Director, Developer Products
Company: Mashery
Email: neil@mashery.com
Web: http://developer.mashery.com
Twitter: @mansillaDEV  @mashery</li></li></ul><li>Mashery API Network<br /><ul><li>Over 100 companies rely on Mashery to m...
Over 115,000 key-holding developers
Over 30,000 active web and mobile applications
Billions of monthly API calls</li></li></ul><li>Mashery API Network<br />
Mashery API Network<br />
What does<br />bad documentation<br />really say about<br />your platform?<br />Your company?<br />
Bad docs say to your users,“I don’t care about you.”<br />Do your docs elicit any of these responses?<br />“Why are these ...
A Few Common Pitfalls That Make for Bad Docs<br />http://www.atarimagazines.com/hi-res/v1n2/davidcrane.php<br />
Technical Overload: Yadda Yadda Yadda <br />Documentation is a general term for a multiplicity of documents in a chosen mi...
data media of any format and for any reproduction,
other content.</li></ul>Common types of documentation include user guides, white papers, on-line help, quick-reference gui...
Technical Overload: Yadda Yadda Yadda <br />Documentation is a general term for a multiplicity of documents in a chosen mi...
data media of any format and for any reproduction,
other content.</li></ul>Common types of documentation include user guides, white papers, on-line help, quick-reference gui...
Too Little a/k/a “Just Enough to Tick You Off”<br />Method: createSituation(s3, s4, s5)<br />This method creates a situati...
Too Little a/k/a “Just Enough to Tick You Off”<br />Method: createSituation(s3, s4, s5)<br />This method creates a situati...
Undocumented changes,deprecations.<br /><ul><li>Changes and deprecations that are not documented
Code samples that no longer work as described</li></li></ul><li>Bad Docs = Angry Developers<br />http://www.flickr.com/pho...
Bad Docs = Angry Developers<br />http://www.flickr.com/photos/gcarvalho/142922427/<br />
Happy Sys Admin Day!http://www.sysadminday.com<br />
Happy Sys Admin Day!http://www.sysadminday.com<br />
Happy Sys Admin Day!http://www.sysadminday.com<br />
Good API Docs<br />http://www.flickr.com/photos/scorpio58/4067099731/<br />
Why are API docs so challenging?<br /><ul><li>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</li></li></ul><li>Rethinking APIDocs Design<br /><ul><li>Rethinking traditional t...
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?</li></li></ul><li>Using Definition Files to Publish Docs<br />> Tradition...
WADL – XML for HTTP/REST
Javadoc – comments in Java</li></li></ul><li>Using Definition Files to Publish Docs<br />Traditional API Definition Format...
WADL – XML for HTTP/REST
Upcoming SlideShare
Loading in...5
×

Maintainable API Docs and Other Rainbow Colored Unicorns

8,133

Published on

My talk @ OSCON covering trends and tips on maintainable API documentation.

Published in: Technology, Business
0 Comments
10 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
8,133
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
0
Likes
10
Embeds 0
No embeds

No notes for slide
  • [ yeah, s/solicit/elicit/ ] ;-)
  • Thanks to everyone who attended. I had a great time, and loved having the discussions during and after the talk. 
  • Maintainable API Docs and Other Rainbow Colored Unicorns

    1. 1. MaintainableAPI Docs andOther Rainbow Colored Unicorns<br />Neil Mansilla<br />Director, Developer Products<br />
    2. 2. Disclaimer<br />The views and statements contained herein are my own (Neil Mansilla)<br />and do not express the views of Mashery, Inc. nor any of its employees,<br />agents, customers, and associates. <br />Also, I’m not a Power Point guru, nor am I Anthony Robbins.<br />
    3. 3. Greetings!<br /><ul><li>Name: Neil Mansilla
    4. 4. Job: Director, Developer Products
    5. 5. Company: Mashery
    6. 6. Email: neil@mashery.com
    7. 7. Web: http://developer.mashery.com
    8. 8. Twitter: @mansillaDEV @mashery</li></li></ul><li>Mashery API Network<br /><ul><li>Over 100 companies rely on Mashery to manage their API infrastructure
    9. 9. Over 115,000 key-holding developers
    10. 10. Over 30,000 active web and mobile applications
    11. 11. Billions of monthly API calls</li></li></ul><li>Mashery API Network<br />
    12. 12. Mashery API Network<br />
    13. 13. What does<br />bad documentation<br />really say about<br />your platform?<br />Your company?<br />
    14. 14. Bad docs say to your users,“I don’t care about you.”<br />Do your docs elicit any of these responses?<br />“Why are these docs so awful?”<br />“Don’t they realize this looks like hell?”<br />“How in the world am I supposed to understand how this thing works?”<br />“Do they no longer support this platform?”<br />“Dude, these guys are bozos.”<br />
    15. 15. A Few Common Pitfalls That Make for Bad Docs<br />http://www.atarimagazines.com/hi-res/v1n2/davidcrane.php<br />
    16. 16. Technical Overload: Yadda Yadda Yadda <br />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.<br />Classical documentation is a set of documents printed on paper. Documentation (to document) also refers to the process of providing evidence.<br />Documentation composure<br />Documentation may include<br /><ul><li>written information for any read, projection or technical performing,
    17. 17. data media of any format and for any reproduction,
    18. 18. other content.</li></ul>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.<br />[edit] Principles for producing documentation<br />The following is a list of guides dealing with each specific field and type:<br /> documentation in health care [5]<br /> thesis writing [6], [7], [8]<br /> Further information: Dissertation<br /> papers for academic journal publishing (i.e. Journal of Food Science [9] and Analytical Chemistry [10])<br />Producing documentation<br />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.<br />[edit] Specializing documentation<br />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.<br />Technical Communication (TechCom) Technical writers document a company's project or service. Technical publication include user guides, installation manuals, and troubleshooting/repair/replace<br />
    19. 19. Technical Overload: Yadda Yadda Yadda <br />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.<br />Classical documentation is a set of documents printed on paper. Documentation (to document) also refers to the process of providing evidence.<br />Documentation composure<br />Documentation may include<br /><ul><li>written information for any read, projection or technical performing,
    20. 20. data media of any format and for any reproduction,
    21. 21. other content.</li></ul>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.<br />[edit] Principles for producing documentation<br />The following is a list of guides dealing with each specific field and type:<br /> documentation in health care [5]<br /> thesis writing [6], [7], [8]<br /> Further information: Dissertation<br /> papers for academic journal publishing (i.e. Journal of Food Science [9] and Analytical Chemistry [10])<br />Producing documentation<br />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.<br />[edit] Specializing documentation<br />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.<br />Technical Communication (TechCom) Technical writers document a company's project or service. Technical publication include user guides, installation manuals, and troubleshooting/repair/replace<br />
    22. 22. Too Little a/k/a “Just Enough to Tick You Off”<br />Method: createSituation(s3, s4, s5)<br />This method creates a situation<br />and takes in three parameters.<br />Method: selectUserByDate(date)<br />This method selects a user by a date.<br />
    23. 23. Too Little a/k/a “Just Enough to Tick You Off”<br />Method: createSituation(s3, s4, s5)<br />This method creates a situation<br />and takes in three parameters.<br />Method: selectUserByDate(date)<br />This method selects a user by a date.<br />
    24. 24. Undocumented changes,deprecations.<br /><ul><li>Changes and deprecations that are not documented
    25. 25. Code samples that no longer work as described</li></li></ul><li>Bad Docs = Angry Developers<br />http://www.flickr.com/photos/gcarvalho/142922427/<br />
    26. 26. Bad Docs = Angry Developers<br />http://www.flickr.com/photos/gcarvalho/142922427/<br />
    27. 27. Happy Sys Admin Day!http://www.sysadminday.com<br />
    28. 28. Happy Sys Admin Day!http://www.sysadminday.com<br />
    29. 29. Happy Sys Admin Day!http://www.sysadminday.com<br />
    30. 30. Good API Docs<br />http://www.flickr.com/photos/scorpio58/4067099731/<br />
    31. 31. Why are API docs so challenging?<br /><ul><li>Never a top priority(until it’s too late, and even then…)
    32. 32. Initial copy can be very daunting
    33. 33. Audience diversity(can’t please ‘em all)
    34. 34. Dynamic platform = maintenance nightmare</li></li></ul><li>Rethinking APIDocs Design<br /><ul><li>Rethinking traditional technical documentation design for APIs by asking:
    35. 35. Is there a better way for developers to learn how to use my platform?
    36. 36. What are the pain points developers are experiencing with my current docs?
    37. 37. How can I maintain my API docs more easily?
    38. 38. What kind of CMS will help us be more efficient?</li></li></ul><li>Using Definition Files to Publish Docs<br />> Traditional API Definition Formats:<br /><ul><li>WSDL – XML for SOAP
    39. 39. WADL – XML for HTTP/REST
    40. 40. Javadoc – comments in Java</li></li></ul><li>Using Definition Files to Publish Docs<br />Traditional API Definition Formats:<br /><ul><li>WSDL – XML for SOAP
    41. 41. WADL – XML for HTTP/REST
    42. 42. Javadoc – comments in Java</li></ul>> Traditional Doc Generating Tools:<br /><ul><li>Oxygen XML
    43. 43. XML Spy
    44. 44. Javadoc Tool</li></li></ul><li>New Web Service Definition Formats & Tools<br />
    45. 45. Google Discovery FormatJSON, RESTful APIs<br />http://code.google.com/apis/discovery/v1/reference.html#resource_discovery<br />URL Shortener API: https://www.googleapis.com/discovery/v1/apis/urlshortener/v1/rest<br />New Web Service Definition Formats & Tools<br />
    46. 46. New Web Service Definition Formats & Tools<br />
    47. 47. New Web Service Definition Formats & Tools<br />Google API Explorer is now open source<br />Java/GWT<br />http://code.google.com/p/google-apis-explorer/<br />
    48. 48. New Web Service Definition Formats & Tools<br />
    49. 49. Wordnik swagr FormatJSON, RESTful APIs<br />http://api.wordnik.com/v4/wordList.json<br />New Web Service Definition Formats & Tools<br />
    50. 50. New Web Service Definition Formats & Tools<br />
    51. 51. Tool Driven and Interactive Docs<br />A New Design Pattern: Interactive Documentation<br />
    52. 52. Interactive Docs<br />A New Design Pattern: Interactive Documentation<br /><ul><li>Learning by exploration and example
    53. 53. API methods and parameters in plain view
    54. 54. Parameter values, types and limits provided
    55. 55. Ability to make live API calls within documentation
    56. 56. Inbound call, outbound header and payload displayed useful for learning, testing and debugging</li></li></ul><li>Mashery I/O Docs<br /><ul><li>Inspired by Wordnik and Etsy JSON schemas
    57. 57. Inspired by Wordnik UI/UX for docs
    58. 58. Built prototype in Node.js</li></li></ul><li>Mashery I/O Docs<br />http://oscon.mansilla.com:3000/usatoday - docs<br />http://oscon.mansilla.com/os/usatoday.json - schema<br /> "usatoday": {<br /> "name": "USA TODAY",<br /> "baseURL": "api.usatoday.com",<br /> "publicPath": "/open",<br /> "auth": "key",<br /> "keyParam": "api_key”<br />}<br />
    59. 59. Mashery I/O Docsin Production<br />http://developer.klout.com<br />http://developer.alibris.com<br />http://developer.fanfeedr.com<br />http://developer.mashery.com<br />
    60. 60. In the spirit of OSCON…<br />Mashery is open sourcing I/O Docs in Node.js<br /><ul><li>Will be posted on Github (finishing the docs )
    61. 61. Includes client interface form generator and back-end proxy API call handler (in same stack)
    62. 62. Deploy on your own server in just minutes
    63. 63. Released under MIT License
    64. 64. Plenty of JSON schemas configured with production APIs
    65. 65. Support for RESTful APIs
    66. 66. Support of OAuth (w/HMAC-SHA1), key passed as parameter, MD5/SHA256 signing</li></li></ul><li>Tomorrow, all day, API Hack Day @ Urban Airship HQ<br />It’s FREE. It’s FUN. It’s FRUN!<br />
    67. 67. I/O Docs Live Demo<br />Time permitting, pick simple API to build I/O Docs<br />Sacrifice tweet to @demogods<br />Go!<br />
    68. 68. Thank you.<br />Questions (and possibly some answers)<br />Contact me:<br /> Email - neil@mashery.com<br /> Twitter - @mansillaDEV<br /> http://developer.mashery.com<br />
    69. 69. Browser URLsHere are a list of URLs that I loaded during my presentation:<br />

    ×