Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Proof of Life by Kelly Hitchcock

Proof of Life by Kelly Hitchcock

More Decks by API Strategy & Practice Conference

Other Decks in Technology

Transcript

  1. Who am I? @KellyHitchcock Spent 10 years as a technical

    writer before transitioning to QA The last 3 of those were spent building expertise in API documentation
  2. Let’s talk doc What we’ll discuss: • The importance of

    good API documentation • What is a content model and why do you need one • What are some key components of a good API doc suite What we won’t: • What tools to use (Swagger vs. traditional authoring tools) • How to take shortcuts with API documentation
  3. Is it really that important? “Ten reasons developers hate your

    API” source: John Musser Reason #1: Your documentation sucks! “12 reasons your API sucks” source: D. Keith Casey Reason #1: Documentation
  4. Pattern recognition The better your API design is, the easier

    it is to create great API docs. Your documentation will highlight every antipattern and bad decision you’ve built into your API. IsNotVisible=0 When pages look different visually, your developers will have a harder time building the connections they need to learn. Inconsistent references slow the learning curve • Operations vs. Methods • URL vs URI • Parameters vs. Arguments
  5. Content models Defines each piece of content and determines where

    each piece fits Documentation patterns for: • Structure • Presentation • Language • Add a user to a group • Configuring group members • How to add users to a group • Group member definition • POST /groups/users
  6. The API Doc Formula GAD=(La+U sc +T r +EM+Fo) Language

    agnostic Usable code samples Token replacements Error messages Flexible outputs
  7. The importance of being agnostic • If you try to

    document specific to each platform, you’ll quickly become overwhelmed • Every time an API entity changes, you’ll have to change the documentation for each platform • Think about translation and i18n
  8. Usable code samples • Whenever possible, make formatting (but not

    line numbers) copy over • Syntax highlighting (Google code prettify) • Keep samples up to date - changing the doc samples should be part of changing the code • Single-click copying • Think about maintaining an external code sample library
  9. Token replacements • Find a way to reuse content for

    entities that appear in several requests or responses • Database, authoring tool, script, etc. • Keep translation and i18n in mind
  10. Error messages • Please don’t let your developers write these

    themselves • Use standard HTTP status codes • Assign error codes, return them in the response, and refer the users to the documentation for the message • A good error message should: ◦ Not blame the user (FAILURE!) ◦ Explain which field in the request caused the error ◦ Demonstrate how to fix it • If they don’t make sense in English, they won’t make sense after translation
  11. More than a reference Just as developer experience is more

    than just having a developer portal, API documentation is more than just having an API Reference. If people can’t adopt your API in the first place, they’ll never use your API reference. If you need a “How to use this documentation,” your documentation is too complicated. • Getting started guides • Tutorials • Community demos • API reference • SDK guides • Helper libraries