Thursday, May 5, 2011

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!


Rave Reviews

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

  • One page for each method. Includes code examples and discussion.
  • Manually written.
  • One page for each topic, narrative tutorial-like structure.
  • Generated with RST and Sphinx, More info here.
  • One page for each method, includes examples and comments.
  • Generated with DocBook (XML), More info here.
  • One page developer's guide with interactive code examples in each section.
  • 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
  • One page for each class, includes both short and long example code, and a popup feedback widget.
  • Uses joDoc for automated generation.
PhoneGap (Method)
  • One page for each method (and example code), with framed (but still linkable) navigation.
  • Manually written.
  • 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.
Yii Framework
  • 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).
Play! Framework
Sencha ExtJS
  • One page for each class, highly linked, inline code examples, and search with auto-complete.
  • Generated using JSDuck and Markdown.
  • 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.
  • One page for each API endpoint ("resource"), with example request and responses in XML/ATOM/JSON.
  • Partially generated from code, manually curated by engineers.
  • 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).

  • One page for each topic, with embedded references and code examples. Complaints: no search/comments.
  • Generated using Sphinx and RST.
  • 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!)

  • 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.
  • 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.
  • Wiki and reference. Complaints: No code examples, hard to find docs.
  • Generated using NaturalDocs.
  • Wiki with articles by topic. Complaints: Hard to navigate.
  • Uses the MoinMoin wiki engine.

No comments: