Roundup: The Best Developer Docs

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!

Screenshots

Rave Reviews

Ordered by popularity, these documentation sets received all positive reviews. Great work!

jQuery	One page for each method. Includes code examples and discussion. Manually written.
Django	One page for each topic, narrative tutorial-like structure. Generated with RST and Sphinx, More info here.
PHP	One page for each method, includes examples and comments. Generated with DocBook (XML), More info here.
CoffeeScript	One page developer's guide with interactive code examples in each section.
Twilio	One page for each topic, includes example requests and responses for REST API and example XML for XML API. Manually written by the engineers.
Mozilla Developer Center	One page for each topic, includes example code, encourages community edits. Uses wiki/social CMS system, MindTouch
PhoneGap	One page for each class, includes both short and long example code, and a popup feedback widget. Uses joDoc for automated generation.
Backbone.js	One page for each method (and example code), with framed (but still linkable) navigation. Manually written.
Yii	One page for each class, lots of internal linking, prominent search with autocomplete. Includes code samples and links to original source code. Generated with custom, open-source PHP tool.
NodeJS	One page for each topic, or can be viewed all on one single page. Includes code examples for each method. Generated using doctool and Markdown.
Play! Framework	Includes step-by-step tutorial and developer's guide (no reference).
Sencha ExtJS	One page for each class, highly linked, inline code examples, and search with auto-complete. Generated using JSDuck and Markdown.
SimpleGeo	Organized by topic with one page for each. Written in a narrative form and includes code examples. Generated using Django and templates, More info here.
Twitter	One page for each API endpoint ("resource"), with example request and responses in XML/ATOM/JSON. Partially generated from code, manually curated by engineers.
Android	Javadoc style, with ability to change language and API level, plus search with auto-complete. Incudes tutorial style articles as well. Generated from code using JavaDoc.

Mixed Reviews

These documentation sets had both positive and negative reviews. (What works for one developer doesn't always work for another).

Python	One page for each topic, with embedded references and code examples. Complaints: no search/comments. Generated using Sphinx and RST.
Facebook	A mix of reference style docs, articles, and github-hosted readmes. Includes search and (Facebook) comments. Complaints: too loosely organized.

Not-So-Great Reviews

These documentation sets had all negative reviews. (Well, they can always improve!)

Ruby	Javadoc style with framesets. Complaints: can't be searched or linked, no per-topic organization. Generated from code using RDoc.
Amazon Products API	Frameset docs, both tutorial and reference style. Complaints: takes many clicks to find the reference, provided sample code does not work.
Paypal	Includes articles and reference docs. Complaints: instructions are dumbed down, deprecated information isn't marked as such, there are too many places to find a piece of information, not enough example code.
OpenLayers	Wiki and reference. Complaints: No code examples, hard to find docs. Generated using NaturalDocs.
CouchDB	Wiki with articles by topic. Complaints: Hard to navigate. Uses the MoinMoin wiki engine.