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.
3. Why do we need good documentation?
What qualities distinguish “good”
documentation?
How can we communicate with
developers?
How can we improve existing
documentation?
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.
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
28.
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
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
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
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
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!