Maintainable API Docs and Other Rainbow Colored Unicorns
•
13 j'aime•16,503 vues
My talk @ OSCON covering trends and tips on maintainable API documentation.
Recommandé
Contenu connexe
Tendances
Tendances (19)
En vedette
En vedette (20)
Similaire à Maintainable API Docs and Other Rainbow Colored Unicorns
Similaire à Maintainable API Docs and Other Rainbow Colored Unicorns (20)
Dernier
Dernier (20)
Maintainable API Docs and Other Rainbow Colored Unicorns
- 1. MaintainableAPI Docs andOther Rainbow Colored Unicorns Neil Mansilla Director, Developer Products
- 2. 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.
- 4. Job: Director, Developer Products
- 9. Over 115,000 key-holding developers
- 10. Over 30,000 active web and mobile applications
- 13. What does bad documentation really say about your platform? Your company?
- 14. 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.”
- 15. A Few Common Pitfalls That Make for Bad Docs http://www.atarimagazines.com/hi-res/v1n2/davidcrane.php
- 17. data media of any format and for any reproduction,
- 18. 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
- 20. data media of any format and for any reproduction,
- 21. 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
- 22. 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.
- 23. 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.
- 26. Bad Docs = Angry Developers http://www.flickr.com/photos/gcarvalho/142922427/
- 27. Happy Sys Admin Day!http://www.sysadminday.com
- 28. Happy Sys Admin Day!http://www.sysadminday.com
- 29. Happy Sys Admin Day!http://www.sysadminday.com
- 30. Good API Docs http://www.flickr.com/photos/scorpio58/4067099731/
- 32. Initial copy can be very daunting
- 33. Audience diversity(can’t please ‘em all)
- 35. Is there a better way for developers to learn how to use my platform?
- 36. What are the pain points developers are experiencing with my current docs?
- 37. How can I maintain my API docs more easily?
- 39. WADL – XML for HTTP/REST
- 41. WADL – XML for HTTP/REST
- 43. XML Spy
- 45. 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 New Web Service Definition Formats & Tools
- 46. New Web Service Definition Formats & Tools
- 47. New Web Service Definition Formats & Tools Google API Explorer is now open source Java/GWT http://code.google.com/p/google-apis-explorer/
- 48. New Web Service Definition Formats & Tools
- 49. Wordnik swagr FormatJSON, RESTful APIs http://api.wordnik.com/v4/wordList.json New Web Service Definition Formats & Tools
- 50. New Web Service Definition Formats & Tools
- 51. Tool Driven and Interactive Docs A New Design Pattern: Interactive Documentation
- 53. API methods and parameters in plain view
- 54. Parameter values, types and limits provided
- 55. Ability to make live API calls within documentation
- 57. Inspired by Wordnik UI/UX for docs
- 59. Mashery I/O Docsin Production http://developer.klout.com http://developer.alibris.com http://developer.fanfeedr.com http://developer.mashery.com
- 61. Includes client interface form generator and back-end proxy API call handler (in same stack)
- 62. Deploy on your own server in just minutes
- 63. Released under MIT License
- 64. Plenty of JSON schemas configured with production APIs
- 65. Support for RESTful APIs
- 67. I/O Docs Live Demo Time permitting, pick simple API to build I/O Docs Sacrifice tweet to @demogods Go!
- 68. Thank you. Questions (and possibly some answers) Contact me: Email - neil@mashery.com Twitter - @mansillaDEV http://developer.mashery.com
- 69. Browser URLsHere are a list of URLs that I loaded during my presentation:
Notes de l'éditeur
- [ yeah, s/solicit/elicit/ ] ;-)
- Thanks to everyone who attended. I had a great time, and loved having the discussions during and after the talk.