As I mentioned in my previous post on "What makes a good Developer Experience?", I'm currently consulting with Flurry to advise them on improving their developer experience. They're starting with a revamp of their documentation and API reference. Per what I wrote in the Documentation chapter from the Developer Support Handbook, good documentation should include tutorial style content, an API reference, and sample code, and should be fully linkable and searchable.
To confirm that my criteria for good docs aligns with what developers in the wild think, I conducted an informal survey on Twitter asking developers for their favorite and least favorite docs. I reviewed their picks, and as I guessed, here's what was common amongst the favorites:
- Easy navigation: everything linked, clear table of contents, every page just takes 1-2 clicks to get to. Example: Yii.
- Easy search:. prominent search box with autocomplete for method/class names. Example: Sencha.
- Reference *and* guide: most offer both a technical breakdown of every part of the API (the reference) as well as a step-by-step narrative guide for using the API. Example: Twilio.
- Inline code samples: in the reference, every class/method comes with example code below the definition, and sometimes that code can even be run in the browser. (Or for HTTP APIs, sample request and responses in every data format are offered). Example: CoffeeScript.
- Comments: a threaded comment system on every page, for developers to discuss issues or usage. Example: jQuery.
And here are some cool bonus features from the favorites (that may not work for everyone):
- Community edits: The Mozilla Developer Center lets anyone login and edit the information themselves.
- Feedback loop: The PhoneGap docs prompt the developers to give them feedback on every page, and they use that to improve the docs.
Many of the favorites are written by the engineers themselves, which likely keeps them more up to date and accurate (and proves that engineers can write!).
The least favorite documentation sets typically suffer from basic usability issues, like lack of search or deep links. When you're writing documentation, you need to remember that your developers won't benefit from it unless they can find it - searchability and linkability should be a top priority.
I've rounded up the documentation sets in the tables below, with links, short description (including how they were generated, if known), and a thumbnail. I've also embedded a slideshow of the screenshots. Feel free to comment with your own opinions on what makes for a great set of developer docs!
Ordered by popularity, these documentation sets received all positive reviews. Great work!
|Mozilla Developer Center|
These documentation sets had both positive and negative reviews. (What works for one developer doesn't always work for another).
These documentation sets had all negative reviews. (Well, they can always improve!)
|Amazon Products API|