The Holy Grail of Kickass API Documentation
Disclaimer: this is a bunch of vaporware.
Read/Write Asymmetry
It’s been a while since people solved the problem of making API documentation easily readable, while keeping it closely tied to the code: keep it in comments in the source code and export it to HTML.
One problem that still remains is that developers suck at writing documentation. They have no need for it (it’s just a waste of time: they already know how that stuff works), and they often don’t use the API they develop themselves, or at least not in all possible use cases, so they end up not knowing very well which information is most valuable to the users.
Users, on the other hand, know it all too well. They know a hack around that quirky behavior; they inadvertently found that undocumented feature (or was it a bug?); they have collectively field-tested it in a hundred times as many use cases as the author had originally foreseen; and they know what needs to be known.
They write about it too! You can see countless blog posts, forum answers, even comments appended to the documentation itself taking up where it left off. It just happens that this stuff never makes its way back into the official docs because it’s too much of a hassle!
If you’re just a user of some library, you usually have it installed in some far-away system directory, outside of source control, and read-only. Making a change to the documentation means finding where the repository is hosted, checking it out locally, finding where in the code that bloody method is implemented, making a change and sending a patch (where to, again?). That’s not your job right?
So why don’t we just make it all a wiki huh? Easy as pie. No funky markup in comment blocks, no generation step, it’s all HTML. You’re reading it, you spot something wrong or incomplete, edit it right there and you’re back to reading before you can say “back to reading.” And where is the code now? Well, somewhere completely dissociated from the documentation. You’re not even sure which version you’re reading about.
So what we really want is API documentation that:
- comes directly from the source code;
- is easily editable as a wiki;
- and goes back to the source code.
There and Back Again
Rdoc.info takes any arbitrary repository and generates API documentation for you. So far it only works for Ruby repositories on Github, but it’s the only one I know so it’s the one I’ll talk about. The idea is applicable to anything that does the same type of auto-generation though.
That’s really cool then! Our first requirement is covered.
The second requirement is making a wiki, so I think we can borrow from about five million solutions.
Now HOW?! How do you turn that stuff back into source code again?!
chmod +w RDoc
Documentation on rdoc.info is generated per repository, per user, so you can decide, for each repository, if its documentation should be wiki-editable or not (if you made it this far I assume you really want it really bad). In that case, all you have to do is create a public branch called “docs”, and rdoc.info starts tracking that instead of the master branch, generating a wiki from it. Now you just tell everyone to come and edit!
Gathering edits
Rdoc.info forks your repository and commits every wiki edit to that fork. It’s quite simple: it just replaces the comment block next to a method/class/whatever with the edited version. On every commit, you receive a pull request.
Displaying
On the website, rdoc.info shows the latest wiki-edited docs by default, with a read-only “canonical” tab showing the last official version that was pushed before the recent edits.
Merging back
When you receive the pull request from rdoc.info, you merge rdoc.info’s branch back into yours, resolving possible conflicts and integrating the changes.
Edit History
What if you push to your “docs” branch when there are wiki commits that you haven’t integrated? Rdocs.info can’t try a normal merge, as there might be conflicts, and the whole thing has to be automatic. If it just does a “reset hard”, it’ll lose previous edits. So it does a merge, but with a no-hostages approach: automatically resolve every conflict by choosing your changes. It will count as a normal edit in the wiki, with the previous version still in the history.
Reverting to a particular version from the wiki interface is the same thing: the contents (only the doc comments, not the code) of the chosen version are commited on top of the current commit, and can be diffed with it.
Attribution, Statistics, Reputation
If the user making the edit is logged in, the commit can have her as the author, and statistics can be kept on who helped out the most and that kind of stuff. Methods with the least content can be marked as “stubs”, and editing those can be worth more points.
More into metadata territory, the developer could also possibly benefit from indirect usage statistics (through clicks and searches), and people up/downvoting individual methods, maybe even commenting on their design (whether they should be split in two; if the parameters or return values make sense, etc.).
You want it too?
From the few services I know which host API docs, I think the most likely to implement something like this are either rdoc.info or ApiDock. So write them and ask for it! (hey, I told you it was vaporware.)
Update: Apparently, something like this has been tried already by DocBox as a Google Summer of Code project. The code on Github is from last year and the website pointed at by RubyFlow seems to be down. Anyone with more info on this?
