Wednesday, January 16, 2008

IDL vs. Human Documentation

Like I said in my previous post, interface definition languages exist for
machines to generate code. They're totally inadequate, though, for instructing
developers on how to write code to use a service. The need for human
documentation in this context isn't quaint or impractical at all -
it's simply reality.

Steve also points out the reams of documentation produced by OMG, and produced
about WS-*, over the years, as a proof point of this.

He's right. Programmers can not survive on IDL alone, or more generally,
meta-data.
Human language
is still often required to express subtleties or non-intuitive aspects of
programming libraries, services, etc., simply because we have no other formal
means of doing so. Or you wouldn't want to read it, if we did.
Human readable documentation is also key to providing overview, introductory,
relationship, etc
type of information.

Overlook the fact that parts of the interface aren't terribly RESTy, if you're a REST purist.
But go out on a limb for me, and pretend they did the right thing in terms of REST; it's not a big leap, I don't think.
Let's ask some questions.
Is there some kind of XML schema that describes the input and output
documents of these service definitions? Nope; can't find one.
What HTTP status codes might get returned? Not documented, though they define
their own error codes returned in the HTTP response payload; that commonly
seen pattern is something else we need to talk about, BTW.
Are ETags in use? Last-Modified checking? Who knows.
etc

So, keep in mind that this documentation is all you've got.
I'm going to claim it's inadequate.

Now the kicker: this API is still perfectly usable!
In fact, I use it every time I write a blog entry,
via a GreaseMonkey script
to generate my little flickr images with annotations.
It's not rocket science! It's HTTP!

While the documentation isn't completely adequate,
it's perfectly acceptable, because I'm only using a small
number of the APIs. The fact that's it's inadequate
is containable. As Steve has previously mentioned, it's
easy to do REPL-ish experiments with REST APIs. Heck,
Flickr includes an API "Explorer" on their site to
let you play, live. Nice!

But here is my fear. It's early days for REST. I want to believe
that we'll see lots of people using REST over the coming decade
to provide 'API's to their services. Where the promise of
DCE, CORBA, WS-* got mired down in their complexities, REST
is simple enough to actually be practical.

And that's my tension. It's simple/easy
(you pick your semantic)
to do simple stuff. I'd like to make sure that it's possible to do hard stuff.
What happens when I need to deal with MORE that just one interface, and those
interfaces are BIGGER than Flickr's? I feel like we're going to get lost in
a sea of differently inadequate documentation. Using meta-data to help describe
at least the nuts+bolts layer, is something that can help. The trick is to make
sure it doesn't get too much in the way, and that you can keep it in sync with
your code. My belief is that both are entirely possible.
BTW, the link in the sentence above is a couple steps back in this conversation
thread, if you've lost your place.

Let me finish this with a challenge. We all agree that documentation is good.
Do you think there's some kind of a standard 'template' that we might
agree on, that could provide all the practical, required information
regarding usage of REST services? All text, prose, for now; just identify the
information actually required. That seems like a worth-while goal, especially
to try to educate people on the "way of REST" - and I'm talking about
RESTy service providers here. Lots of people don't get REST. Let's teach them, by example,
and by the way, I'm sure I still have a lot to learn myself.

You never know; I may see that prose and say
"My gods. I've been such a dumb-ass! I can see that there's no way to formalize that to some machine readable
format!". But I'll bet you a beer, that I won't say that. Take that prose,
create an XHTML template that you could style, morph it into a MicroFormat (might not be so micro),
create a JSON mapping when JSON takes over the universe this year, etc.
Now I got my meta-data and I'll stop yammering on about it (not likely). But baby steps for now.
I'd be happy with prose for now. Let's go top-down.

One more final note :-) I wrote this post last night, before
Tim Bray
posted about 'therestfulway.com'.
Synchronicity? Wouldn't it be great to have a whole site full of patterns, best practices,
examples, etc on REST? I've posed this question before, and gotten some positive responses.
But some action is obviously required. I can't do it alone, but I'd be happy to help.
I'm willing to sign a waiver indicating I won't talk about meta-data for the first six months.
Who can pass that up?