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
×

other content.</li></ul>Common types of documentation Maintainable API Docs and Other Rainbow Colored Unicorns

13.718 Aufrufe

Veröffentlicht am

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 documentationThe 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 documentationTechnical 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 documentationMarketing 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

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

×