Proof of Life by Kelly Hitchcock

Transcript

1. Proof of Life Your API documentation is your API
2. 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
3. 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
4. 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
5. 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
6. 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
7. The API Doc Formula GAD=(La+U sc +T r +EM+Fo) Language agnostic Usable code samples Token replacements Error messages Flexible outputs
8. 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
9. 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
10. 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
11. 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
12. Flexible outputs
13. 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
14. 200: OK @KellyHitchcock