Documenting APIs with Cats
•Download as PPTX, PDF•
2 likes•1,364 views
Sample code and documentation are important when engaging a developer audience, but what are the guidelines? How can you maintain consistent tone across languages, platforms, and levels of developer experience? We'll compare some leading developer documentation sites and discuss strategies for keeping documentation and sample code content consistent, comprehensive, and concise.
Recommended
Recommended
More Related Content
Viewers also liked
Viewers also liked (14)
Similar to Documenting APIs with Cats
Similar to Documenting APIs with Cats (20)
Recently uploaded
Recently uploaded (20)
Documenting APIs with Cats
- 3. Why do we need good documentation? What qualities distinguish “good” documentation? How can we communicate with developers? How can we improve existing documentation?
- 4. Do we really need great docs? YES!
- 7. Good documentation is good • Decreases barriers to entry • Decreases support costs • Works as a marketing tool
- 8. When evaluating an API… http://www.programmableweb.com/news/api-consumers-want-reliability- documentation-and-community/2013/01/07
- 10. zero to “Hello World”
- 13. Bad documentation makes your users skeptical …
- 14. … or sad.
- 17. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
- 18. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
- 19. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
- 20. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
- 21. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
- 22. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
- 23. Types of Docs • Technical Reference • Sample Code/Code Snippets • Tutorials (written, video, interactive) • Application Samples • Q&A Resources
- 24. Technical Reference • Describe everything in your API – Even things you don’t want people to use • Structure should follow the structure of the API – But can intentionally diverge • Primarily values: comprehensive, navigable • Shortcuts: API design, ‘automatic’ documentation, formatting
- 27. Automatic Documentation • Less error-prone • Takes less time … but it’s only part of the story! • Documentation needs to explain things to people – Different writing skills • Communication is too important to play second fiddle in comments
- 29. Code Snippets • Allow users to learn by example • Demonstrate a single call • Need to be able to copy/paste content – Must work! • Primary values: painless • Code should be simple, readable (not clever) • Example: Stripe, Twilio
- 35. Which Languages? • At least three languages • At least one raw call/response sample • Two additional samples implies multi-language support • Popularity • Target audience • The more the merrier • as long as they’re maintainable
- 37. IEEE Spectrum: Top Programming Languages (web) http://spectrum.ieee.org/static/interactive-the-top-programming-languages#index
- 38. Fancy Code Snippets via interactive console • Allows users to play with data • Real calls to API • User credentials, parameters • Tools: - Mashery I/O Docs - Apigee - 3scale
- 46. Tutorials • Your product probably has some subtlety – Authorization – Security concerns – Expected workflow • Can take many formats – Step-by-step articles – Videos/screencasts – Interactive • Key Values: successful, painless
- 54. Application Samples • More fully-fledged “learning by example” • Full integration within an application context • Larger samples • More like a POC • Primary values: readability, navigability • Example: Twilio
- 56. Q&A resources • There will still be unanswered questions – Specific use cases – Combinations of resources • Public answers benefit the community • Primary values: navigability, simplicity
- 61. A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service. • Technical Reference • Sample Code/code snippets • Tutorials (written, video, interactive) • Application Samples • Q&A resources
- 62. Do I really need all those things?
- 63. Top 10 APIs Article • Facebook • Google Maps • Twitter • YouTube • AccuWeather • LinkedIn • Amazon Product Advertising • Pinterest • Flickr • Google Talk http://www.programmableweb.com/news/most-popular-apis-least-one-will-surprise-you/2014/01/23 http://www.programmableweb.com/apis (As of 2015-02-09) Popularity • Facebook • Kayak* • Google Maps • Skype • Waze • Netflix* • Fresh Logic Studios Atlas* • Yahoo Weather • AirBNB* • Twitter
- 64. What documentation do they offer? Technical Reference Code Snippets Tutorials Interactive Console SDK Application Samples Q&A Facebook yes yes yes yes yes yes yes Google Maps yes yes yes no yes no stack overflow Twitter yes JSON only yes yes some no yes YouTube yes yes yes yes yes no stack overflow AccuWeather yes no* yes no no no no LinkedIn yes yes yes yes 3rd party no yes Amazon Product Advertising yes 3rd party yes no 3rd party 3rd party yes Pinterest yes no yes no yes no no Flickr yes 3rd party yes yes 3rd party no yes Google Talk** yes yes yes no yes no yes Twilio yes yes yes no yes yes yes Skype URI yes yes yes no no no yes Waze yes yes yes no no no yes Yahoo Weather yes yes yes yes no no yes * Does provide a JavaScript sample for one resource ** Replaced May 2013, no longer updated
- 65. Comprehensive vs. Concise? • Comprehensive – Full coverage for technical references – Common use cases for tutorials/samples • Length becomes an issue – affects navigation - dilutes understanding - impacts maintenance
- 66. Information that isn’t accessible isn’t helpful.
- 67. Keep it up to date! • Inaccurate is as bad as missing • Only way to make integrations maintainable
- 68. Creating Documentation • Don’t build it from scratch • Evaluate the best description format for you • Use existing tools to make your site all fancy • Continue to evolve
- 80. So much more! • SDKs • Developer Blog • Posted Release Notes • Formatting tools • XML-based docs • Auto-doc tools • Open source docs
- 82. Thanks! Anya Stettler Developer Relations Avalara anyarms anya.stettler@avalara.com slides available at http://www.slideshare.net/AnyaStettler
Editor's Notes
- I'll talk about why good documentation is so important. I'll cover some different ways to engage with developers through documentation and what qualities you should look for in each of those methods. We'll take a look at some examples of good documentation for each of those. Then we'll take a look at some hypothetical, terrible documentation and refactor it into good documentation. That should be the fun part.
- Let's start easy. I hope you're all in agreement with me on this one: your API needs documentation.
- No API is entirely self-explanatory. You may have the most elegant, intuitive API possible, but you still need documentation. And I don't mean just a list of fields with descriptions. That's essential, but it needs to go deeper than that. There are complexities to your business. To your product. Those need to be clear to your users. There are a lot of other talks here about helping machines communicate with other machines. That's not what I mean here. This is communicating with humans.
- In practice…
- More specifically If your documentation is good, it can do some great things. Here are the easy ones: - It decreases barriers to entry. It's easier to use your product since it's well documented, so it takes less time and effort to get it up and running. - It decreases support burden and costs. Developers aren't calling or emailing with as many questions, and as they continue to modify or update their code, they have a reference to go back to. Even if you walk them through it step by step now, after six or eight months, they'll forget all that information. Write it down! Make it accessible. It's less expensive for you and for them. So, In addition to being purely informative, what else can documentation imply to your developer customers? It can reduce costs of implementation and support and all that, but it also works as a marketing tool.
- Often, you're selling a product to a business guy. This is a business cat – he is wearing a tie. He's going to make the decision that this product looks like it meets the business needs. He's not going to be writing the code, but he's maybe a tech-literate guy, and as part of the evaluation process, he wants to make sure that his dev will have what he needs to get the job done. If you can send him to documentation that is clearly easy to navigate and even just appears to be helpful, that goes a long way towards reassuring him. This is a developer cat – he is wearing a hoodie. When his dev looks at it, he also impressed and reassured, and the integration process looks easier.
- This marketing perspective isn’t a full evaluation of everything your API can do. Not yet. This is just 'can I make a request and get a response'? How does it feel when I kick the tires? If that incredibly basic request/response is easy, it makes me feel like a successful reader. It will certainly get trickier, but I have one easy win under my belt. I can do this - no problem. If the 'zero to hello world' seems too complicated, well, that was the easiest thing of all the things I will need to do. It's only going to get harder as I try to reflect more complicated use cases and look at more complicated representations. I'm defeated before I begin.
- If your documentation is bad, there are a couple of things users might think. They might think that if your documentation is shoddy, your product is also shoddy. That the quality of the documentation accurately reflects the state of your service. In that case, they will doubt that your product can actually deliver on what you promised in your much swankier marketing materials. Okay, let's call that the worse case. That your bad documentation undermines any perception of a quality product. That sounds pretty bad.
- In the very best case, they give you the benefit of the doubt that your product does, in fact, work as advertised (and as well as advertised). In that case, you must not care about engaging developers as an audience. Their success and ease of product use is not important to you as a business. And that's not nice either. That's our best case. That your readers assume that everything else is great, just not this one incredibly essential part of their engagement with you and your company. And that they are not important to you. So much so that you have not bothered to write down the answers to questions you know they will have. 'What are the resources I can call and how do I call them?' What will happen when they come up with other, more meaningful, questions? Harder questions? What kind of support should they expect in those cases?
- If you have bad documentation, it’s not the end of the world. When I started in my group, we emailed developers a 35-page PDF document. There was no central location where the PDF was available, so people were always asking each other “is this the latest one? Do you have the latest one?” which was kind of a joke, because the document had no relation to our service versioning.
- It had an index. So, that was our documentation. We’ve come a long way since then, but that’s where we started.
- So. Good documentation is good. Super. What makes documentation good? A feature-complete, self-service resource that provides users with all the information necessary to build a painless, maintainable, successful integration to your service. What do I mean here? Feature-complete. everything is documented. even things you don't really want people to use. If it's out there, and they could possibly find it, it needs to be documented. If you don't want them to use something, by all means, document that. Self-service. users can find what they need without assistance. Painless. that's bringing back our 'zero to hello world' concept, but bigger. This is all the things that are undeniably necessary (technical references), as well as the things that make integration much much easier. Things like sample code, tutorials that cover use cases, etc. This is the big content driver, we'll talk about this more later. Maintainable. in two years when some other dev opens up the integration code, will they be able to see what your API did then? Will they be able to make enhancements? Will they be able to udpate to the latest API version? Are you, as a documenter, confident that you are updating everything that needs to be updated when a new release is pushed to production? Successful. if there are industry concerns that you have - if there are particular use cases that require special attention, you need to make sure to cover all of them. If you are payment processor, and you need to impress upon your users the need to not store credit card information, that's something that needs to be included.
- So. Good documentation is good. Super. What makes documentation good? A feature-complete, self-service resource that provides users with all the information necessary to build a painless, maintainable, successful integration to your service. What do I mean here? Feature-complete. everything is documented. even things you don't really want people to use. If it's out there, and they could possibly find it, it needs to be documented. If you don't want them to use something, by all means, document that. Self-service. users can find what they need without assistance. Painless. that's bringing back our 'zero to hello world' concept, but bigger. This is all the things that are undeniably necessary (technical references), as well as the things that make integration much much easier. Things like sample code, tutorials that cover use cases, etc. This is the big content driver, we'll talk about this more later. Maintainable. in two years when some other dev opens up the integration code, will they be able to see what your API did then? Will they be able to make enhancements? Will they be able to udpate to the latest API version? Are you, as a documenter, confident that you are updating everything that needs to be updated when a new release is pushed to production? Successful. if there are industry concerns that you have - if there are particular use cases that require special attention, you need to make sure to cover all of them. If you are payment processor, and you need to impress upon your users the need to not store credit card information, that's something that needs to be included.
- So. Good documentation is good. Super. What makes documentation good? A feature-complete, self-service resource that provides users with all the information necessary to build a painless, maintainable, successful integration to your service. What do I mean here? Feature-complete. everything is documented. even things you don't really want people to use. If it's out there, and they could possibly find it, it needs to be documented. If you don't want them to use something, by all means, document that. Self-service. users can find what they need without assistance. Painless. that's bringing back our 'zero to hello world' concept, but bigger. This is all the things that are undeniably necessary (technical references), as well as the things that make integration much much easier. Things like sample code, tutorials that cover use cases, etc. This is the big content driver, we'll talk about this more later. Maintainable. in two years when some other dev opens up the integration code, will they be able to see what your API did then? Will they be able to make enhancements? Will they be able to update to the latest API version? Are you, as a documenter, confident that you are updating everything that needs to be updated when a new release is pushed to production? Successful. if there are industry concerns that you have - if there are particular use cases that require special attention, you need to make sure to cover all of them. If you are payment processor, and you need to impress upon your users the need to not store credit card information, that's something that needs to be included.
- So. Good documentation is good. Super. What makes documentation good? A feature-complete, self-service resource that provides users with all the information necessary to build a painless, maintainable, successful integration to your service. What do I mean here? Feature-complete. everything is documented. even things you don't really want people to use. If it's out there, and they could possibly find it, it needs to be documented. If you don't want them to use something, by all means, document that. Self-service. users can find what they need without assistance. Painless. that's bringing back our 'zero to hello world' concept, but bigger. This is all the things that are undeniably necessary (technical references), as well as the things that make integration much much easier. Things like sample code, tutorials that cover use cases, etc. This is the big content driver, we'll talk about this more later. Maintainable. in two years when some other dev opens up the integration code, will they be able to see what your API did then? Will they be able to make enhancements? Will they be able to update to the latest API version? Are you, as a documenter, confident that you are updating everything that needs to be updated when a new release is pushed to production? Successful. if there are industry concerns that you have - if there are particular use cases that require special attention, you need to make sure to cover all of them. If you are payment processor, and you need to impress upon your users the need to not store credit card information, that's something that needs to be included.
- So. Good documentation is good. Super. What makes documentation good? A feature-complete, self-service resource that provides users with all the information necessary to build a painless, maintainable, successful integration to your service. What do I mean here? Feature-complete. everything is documented. even things you don't really want people to use. If it's out there, and they could possibly find it, it needs to be documented. If you don't want them to use something, by all means, document that. Self-service. users can find what they need without assistance. Painless. that's bringing back our 'zero to hello world' concept, but bigger. This is all the things that are undeniably necessary (technical references), as well as the things that make integration much much easier. Things like sample code, tutorials that cover use cases, etc. This is the big content driver, we'll talk about this more later. Maintainable. in two years when some other dev opens up the integration code, will they be able to see what your API did then? Will they be able to make enhancements? Will they be able to update to the latest API version? Are you, as a documenter, confident that you are updating everything that needs to be updated when a new release is pushed to production? Successful. if there are industry concerns that you have - if there are particular use cases that require special attention, you need to make sure to cover all of them. If you are payment processor, and you need to impress upon your users the need to not store credit card information, that's something that needs to be included.
- So. Good documentation is good. Super. What makes documentation good? A feature-complete, self-service resource that provides users with all the information necessary to build a painless, maintainable, successful integration to your service. What do I mean here? Feature-complete. everything is documented. even things you don't really want people to use. If it's out there, and they could possibly find it, it needs to be documented. If you don't want them to use something, by all means, document that. Self-service. users can find what they need without assistance. Painless. that's bringing back our 'zero to hello world' concept, but bigger. This is all the things that are undeniably necessary (technical references), as well as the things that make integration much much easier. Things like sample code, tutorials that cover use cases, etc. This is the big content driver, we'll talk about this more later. Maintainable. in two years when some other dev opens up the integration code, will they be able to see what your API did then? Will they be able to make enhancements? Will they be able to update to the latest API version? Are you, as a documenter, confident that you are updating everything that needs to be updated when a new release is pushed to production? Successful. if there are industry concerns that you have - if there are particular use cases that require special attention, you need to make sure to cover all of them. If you are payment processor, and you need to impress upon your users the need to not store credit card information, that's something that needs to be included.
- If this is the goal we're trying to achieve, what are the elements we can use to reach this goal? I'm going to talk about five different types of documentation. You should offer all of them. Technical reference This is what most people think of when they think of API documentation. What are the bare facts of calling your API? what are the resources, methods, parameters, so on. Sample code/code snippets These are copy-pasteable bits of code that demonstrate a particular use. Just one call - not a whole use case. Tutorials (written, video, interactive) Explanation of particular use cases or workflows Application samples Sample code with context. This is often a (bare-bones) stand-alone application that includes integration to your API. Q&A resources Somewhere people can go when they're unsure.
- A description of something should follow the structure of the thing itself. In that way, even the structure of your documentation can imply the structure of your API. After all, your documentation is the human-discoverable representation of your API. If your API is well-designed and well-structured, if it really is intuitive, you can avoid some amount of volume in your documentation. Not because those things don't need documenting - they do! They're just documented elsewhere. The biggest pain points in usability are when things don't do what your user expects - you need to document those things incredibly carefully.
- Stellar is a decentralized protocol for sending and receiving money in any pair of currencies
- Documentation is iterative. And even a little can go a long way.
- Remember that PDF documentation?
- 3 ½ years ago…
- 86 cases (last August) to 12 cases (last month)
- With all these tools and resources available to you, I hope you’re inspired to brush up your documentation!