Right Ingredients for your API Documentation
•Download as PPTX, PDF•
1 like•1,719 views
When in France, right?! After interviewing dozens of API influencers for APIdays Paris on the importance of API documentation, two themes constantly arose: 1. Documentation is the most important factor for decision making in the API economy. 2. All API documentation sucks. So even if you don't have a big budget to cultivate developer experience, this talk is filled with small often forgotten things like how each API handles OAuth (the number one tech support question!) Read some tips that any budget should address. presented at: http://apidays.io written and presented by: http://ebranding.ninja book it is based on: http://apidocswriter.com/
Recommended
Recommended
More Related Content
Viewers also liked
More from eBranding Ninja
More from eBranding Ninja (7)
Recently uploaded
Recently uploaded (20)
Right Ingredients for your API Documentation
- 1. The importance of the right ingredients for your API documentation “How to leave your customers without a bad taste in their mouths.” @jkrggins#APIdays
- 2. Developer experience is the most important part of the API economy • Designing an engaging experience around your API. • Managing the entire API lifecycle. – IBM 2016 • With the popularity of microservices, developers are your decision makers. They will judge your API in a manner of seconds.
- 3. “My friend’s bakery burned down last night. Now his business is toast.” Why API documentation IS your business.
- 4. Devs eat documentation for lunch – ProgrammableWeb 2013
- 5. – James Yu, Parse “The way to a developer’s heart is great documentation.”
- 6. “A good baker will always rise to the occasion, it’s the yeast he can do.” Documentation-First: How to build an API for your consumer
- 7. – Garen Torikian, Github “If I can’t describe it and I’m working around something in the documentation, then I need to fix something in the code.”
- 8. Complicated documentation is a sign your code is too complicated.
- 9. – Rich Visotcky, agile coach “Whenever we updated the method, the documentation port was right at the top. Our code we kept between two and 30 lines per method. If they went much beyond that, they were breaking stuff down.”
- 10. In Scrum, “Documented” is the perfect definition of “Done.”
- 11. – Arnaud Lauret API Handyman “Even if you provide an internal API, you should create documentation, just like you do if you sell it as a product. The people will consume it and use it.”
- 12. Documentation isn’t everything 1. Good documentation can’t fix a bad API. A lot of people fix bad APIs by just writing a lot of documentation. 2. A good API can’t be used without good documentation. – Greg Koberger, ReadMe
- 13. Hello World:You have 3 minutes, 33 seconds to sell your API “A baker stopped making donuts after he got tired of the hole thing.”
- 14. The DX-journey begins with three questions 1. What does it take for them to be onboarded? 2. How do they get successful with the API? 3. How are they running their business with the API? – Romain Huet, Stripe
- 15. 3:30:3 30:3:30 Litmus Test • Understand in 3 seconds what your API is for. • Be able to identify the entry point in 30 seconds. • Be able to create an account, call the system, and use the result in 3 minutes – Ori Pekelman, Platform.sh
- 16. Never ever forget • Authorization • OAuth • Terms & Conditions – Bruno Pedro, Hitch
- 17. Which ingredients will make your API trés magnifique? “Bakers trade bread recipes on a knead to know basis.”
- 18. –“Winning the API Economy,” 3scale by Red Hat “Excellent documentation also saves support effort and speeds the time it takes customers to go live.”
- 19. Stop telling. Start showing! • Copy-pastable code samples • Then answer the following questions: What are the objects? Resources? What are the operations? What are perimeters? What’s the data in and out? Was it successful or not? – Uri Sarid, MuleSoft
- 20. Set their expectations • Call limits • Pricing • API error codes • Endpoints
- 21. Create great documentation or you might as well not create an API at all. “If you can’t take the heat, stay out of the kitchen.” @jkrggins #APIdays
- 22. Tweet a selfie with your copy to #APIdays and tell us which influencer interviewed you trust the most with your API advice. “Crust me. I’m on a roll.”
Editor's Notes
- How many people develop APIS? How many of you think your documentation is good enough? I spent more than a month interviewing dozens of API influencers about what is often, wrongly, perceived as boring and unimportant. What I found is that it’s anything but boring. It’s kind of the most important thing And then being an American speaking for the first time in France, it seems only appropriate to make it entirely baguette themed.
- Just like people buying your stuff is the most important and measurable part of the consumer industry, developers are buying your products meaning developer experience makes the API economy go round. This means: Designing an engaging experience around your API. Managing the entire API lifecycle. And while IT or CTOs were usually the big decision makers, now that we’ve broken away from the kingdom of the monolith which could only have one leader, microservices and containers are empowering individual devs as decision makers.
- And the most important part of that developer experience and decision making IS docs. If you don’t want your business to be toast too, your API needs documentation. And yet now matter how many statistics say it is the most important part to API adoption, while companies are investing more and more in APIs and entire platforms, they aren’t investing that much more into proper documentation.
- Guess what, it’s not good enough. In a huge 2013 ProgrammableWeb study, API consumers felt that “complete and accurate documentation” outshined even uptime as the highest factor into their API decision making.
- Like great wine to anyone not pregnant, documentation is an API addiction rarely satisfied. Now there are amazing tools and description languages interviewed and written a lot about in this book to help you automate some side of documentation and then it talks a lot about the human side of documentation too. But since this is a mere 20-minute talk, I focused on the most basic things, that even if you have no budget for documentation, you HAVE to include these pieces to success
- Taking API-first design another step further, is documentation-first design If I were to ever ever ever code, I would do this anyway because I fear those black coding screens, and Doc-First design is about writing or sketching it all out before you even write a single line of code
- Github’s Garen starts this process by drafting use case documentation, a brief white paper or breakdown of what the API should be doing. He says these are mostly internal notes, but it’s a good way to get started before going back and forth between coding and documentation. complicated documentation is a red flag that the code itself is too complicated. In the interview, Garen said, “If you’re writing steps in a document — like iterating access tokens or getting setup for authorization — if there’s a mistake, by the time you’re getting to the documentation, you have to explain too fully the use case and over-explain workarounds.” By writing doc-first you simplify the code, which in turn makes it makes the documentation process simple.
- Rich built software for building management. He pointed out that if you have to scroll too much — more than half a screen — everything is getting too large and complicated. Doc-first and continuous documentation prevents that problem. Plus, how many people hear follow some form of Scrum? How many make “documented” the meaning of “Done?”
- First, to explain this slide, which exhibits my failure as a journalist who not only calls Ar-no the API Handyman because I suck at pronouncing his name, but then I spelled it wrong one too many times. And so this is my public apology. Shame I just copy-pasted the name over and over again so I will probably misspell again, but I guess saving it into my MacBook dictionary will help. But the point of this quote and slide is a reminder not to forget internal documentation! Arnaud was in the common situation at AXA Bank where he was producing an API and documentation that he wasn’t going to consume. Often when you are creating documentation, you have spent so much time creating an API that you forget how to dogfood and use it from your end user’s perspective. Add to that, yes it was an API for internal usage, but Arnaud and his colleagues were in the banking section, but their API consumers were in the insurance company, so preparing then passing over the wall isn’t how it should be done, you should have documentation and your customers factored in from the start.
- • Good documentation can’t fix a bad API. A lot of people fix bad APIs by just writing a lot of documentation. • A good API can’t be used without good documentation.
- “If someone is struggling with API for a long time, they will just lose interest.” A getting started should be about finding the perfect balance between just enough and too much.
- • What does it take for them to be onboarded? • How do they get successful with the API? • How are they running their business with the API?
- At Stripe, they kick it off with a Quick Start Demo, where you can actually click on the snippet and use the code without even signing up. Then later when you want to complete your integration and process live payments, you have to finish your registration. This reduces the friction of long signup forms. And with Stripe you can even click your language of choice and copy and paste the snippet. The documentation is really tailored and personalized for you, including automatic translation to Ruby, Python, PHP, Java and Node. Then Stripe includes demos right within documentation. Yes this sounds like they spend a lot more time and money on their documentation, but a lot of you have demos already, why wouldn’t you link to them in the right spots of the documentation?
- Hitch’s Pedro also warned there are two documentation sections where you should be more careful because they’re related with how end users of third-party apps will interact with your API and how their perception might be a affected. These are often what the developers are considering in the getting started phase as they consider your API: Authorization: If you allow API consumers to act on behalf of users, you should provide concise documentation explaining exactly how the authorization works and what options are available to developers and their users. One thing interviewees repeatedly pointed out was that they field so many questions about OAuth — we take it for granted that everyone understands OAuth, but actually just about every API treats it differently. And most don’t include it in the docs at all Terms and conditions: You should clearly describe what you allow developers to do with your API and what your responsibilities are to end users. Here you also include a list of the main things that you will not allow, revoking access if it is violated.
- Besides the basic Hello World, once you get them in, strongly considering adopting your API, what can you do to not only close the deal but to make your API kill so much that not only do they use your API but they succeed with it on their own.
- Because, when you have your shit together with great documentation, not only are you creating a repeatable profitable developer experience, you save loads of time and money on customer support because your customers are autonomous.
- ReadMe’s founder Greg said “APIs seem shockingly hard to use and I don’t understand why.” One of those reasons is because we bore people with a dictionary and then follow it up with a few static examples. Nobody learns how to play the cello by simply watching someone else do it. They learn it by playing it themselves. That means code examples that you can just copy-paste yourself • What are the objects? Resources? • What are the operations? • Like all users within a certain zip code, What are the perimeters I can pass in it? • What’s the data in and the data out? • Was it successful or not? How do I know if it was successful or not?
- This is a really important part to DX or the developer experience. It may seem stupid, but a lot of the time the terms and conditions are totally lacking in documentation. What are the call limits? And then using chatbot tech soon, soon we can upsell it. Then explain your error codes. Like Stripe talked about today the 402 error code which strongly affects payment processes but most don’t know about. And again OAuth errors. Then explain how to overcome these errors. Illustrate all endpoints In the end, good documentation is about answering, “What are some things I as the user could be doing to not anger the server that I’m talking to?” And then, only when you have covered these parts will you be able to then touch base on what you think is important. Of course then you shouldn’t be doing what you think is important and start asking your customers!
- So that is just a rapid summary of my book — maybe 4%. Hope you’ll at least take it home and skim it! I would like to say thank you to everyone I interviewed for this book. To our sponsors, APIary, Synergistech, Restlet, the Open API Initiative and of course Mehdi and APIdays. And a special thanks to the API community. This isn’t the usual tech kill-or-be-killed competitive landscape. I think the API community is an actual community not like the bullshit word often thrown around by use marketers because, first, we work with a technology that literally brings people and data and services together, and because we realize that as APIs will drive so much more of the future including the Internet of Things, all things mobile, and many things tech, if we work together we can succeed even more. I’m proud to call myself a member of this community. Add to this that we have a strong agreement that API documentation IS the way to make the API economy a success, though we don’t always act like it.
- And now, I end my talk like all in the API community. Do your part to promote it! Make sure you tweet a lot to the #APIDAYS hashtag and that you write your own API stories yourself — we all have an obligation to market it. And if you want, take a selfie with my book and tweet it to #APIdays. Bonus points if you happen to have a baguette in that selfie!