Documenting APIs with Cats

Editor's Notes

• #4: 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.
• #5: Let's start easy. I hope you're all in agreement with me on this one: your API needs documentation.
• #6: 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.
• #7: In practice…
• #8: 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.
• #10: 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.
• #11: 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.
• #14: 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.
• #15: 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?
• #16: 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.
• #17: It had an index. So, that was our documentation. We’ve come a long way since then, but that’s where we started.
• #18: 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.
• #19: 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.
• #20: 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.
• #21: 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.
• #22: 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.
• #23: 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.
• #24: 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.
• #25: 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.
• #49: Stellar is a decentralized protocol for sending and receiving money in any pair of currencies
• #70: Documentation is iterative. And even a little can go a long way.
• #71: Remember that PDF documentation?
• #72: 3 ½ years ago…
• #80: 86 cases (last August) to 12 cases (last month)
• #82: With all these tools and resources available to you, I hope you’re inspired to brush up your documentation!