Right Ingredients for your API Documentation
-
Upload
ebranding-ninja -
Category
Technology
-
view
195 -
download
0
Transcript of Right Ingredients for your API Documentation
The importance of the right ingredients for
your API documentation
“How to leave your customers without a bad taste in their mouths.”
@jkrggins#APIdays
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.
“My friend’s bakery burned down last night. Now his business is toast.”
Why API documentation IS
your business.
Devs eat documentation for
lunch
– ProgrammableWeb 2013
– James Yu, Parse
“The way to a developer’s heart is great documentation.”
“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
– 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.”
Complicated documentation is a sign your code is too complicated.
– 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.”
In Scrum, “Documented” is the perfect definition of “Done.”
– Arnaud LauretAPI 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.”
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
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.”
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
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
Never ever forget
• Authorization
• OAuth
• Terms & Conditions
– Bruno Pedro, Hitch
Which ingredients will make your API trés
magnifique?
“Bakers trade bread recipes on a knead to know basis.”
–“Winning the API Economy,” 3scale by Red Hat
“Excellent documentation also saves support effort and speeds the time it
takes customers to go live.”
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
Set their expectations
• Call limits• Pricing• API error codes• Endpoints
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
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.”