Document your clients, not your technology

As previously alluded, I’ve been doing some work in riak recently.  Specifically, I’ve been doing work in the riak ruby client, since one of the advantages of Ruby (and other high-level languages like Python) is that you can use gems to have a nice interface and abstraction layer on top of the services you use.

And the ruby riak client game is, indeed, produced, published, and maintained by Basho.  As it should be: it’s their bid to get Ruby programmers to think about riak.

Riak itself has a wealth of documentation, something on the general order of 100 pages of documentation that is essentially useless to developers.  It’s probably of some use to administrators of the system, but in the many days of frustrated googling trying to figure out how to do something in riak, I’ve never once had one of those pages come in handy.

The client gem has four pages of documentation.

I remain, after months of developing in riak, unsure whether I am using secondary indices or riak search on the system that we’re searching several times a second.  Really!  Genuinely!  And I’m not alone, my colleagues are equally bewildered.

I’ve been trying to make use of the gem’s conflict resolution system.  There are zero (0) examples of how to use it.  Here is the entirety of the documentation for the conflict resolution system:

    # Defines a callback to be invoked when there is conflict.
    # @yield The conflict callback.
    # @yieldparam [RObject] robject The conflicted RObject
    # @yieldreturn [RObject, nil] Either the resolved RObject or nil if your
    # callback cannot resolve it. The next registered
    # callback will be given the chance to resolve it.
    # @note Ripple registers its own document-level conflict handler, so if you’re
    # using ripple, you will probably want to use that instead.
    def self.on_conflict(&conflict_hook)

Well, thanks, guys.

This is seriously not okay.  The ruby riak gem isn’t a labor of love of some random person, it’s the way for one of the most popular programming languages around to use riak.  It needs to be a first class citizen from Basho’s perspective.  The fact that it’s an abstraction of the core riak interface is great, but when a developer needs to dive in and get at the nitty gritty details, the documentation needs to step up and explain what is being abstracted away.  This is particularly true given the number of complexities and traps Riak has built into it.

Having good conceptual overview and systems administration documentation is great.  But your fancy new technology (and this is far from a problem unique to Basho/riak) is only as good as the code that people write on top of it.  There’s no excuse for building an API and just shrugging and telling people to figure it out.

The views expressed here are my own, and may not reflect those of my employer.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s