Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.
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
Nächste SlideShare
Wird geladen in …5
×

Javadoc – comments in Java</li></li></ul><li>Using Maintainable API Docs and Other Rainbow Colored Unicorns

13.809 Aufrufe

Veröffentlicht am

Javadoc – comments in JavaUsing Definition Files to Publish DocsTraditional API Definition Formats:WSDL – XML for SOAP

Veröffentlicht in: Technologie, Business
  • Als Erste(r) kommentieren

×