I spent much of yesterday looking at SproutCore, which seems to be a rather nice open-source web app framework. While getting to know the framework, I came up against a problem I’ve seen in many similar frameworks. I’m calling it the missing middle documentation.
The issue is that documentation typically comes in two varieties:
- A friendly tutorial covering a simplified application
- Low-level class and method reference
Between the two, there’s a massive gap. Reading a one-hour tutorial simply doesn’t get you to the level where a class reference is a useful resource. It’s like handing a beginning English learner nothing but an abridged dictionary.
Depending on the project, the gap can be gaping open or patched with a mish-mash of wiki pages, blog posts and forums. You simply don’t know where to go to learn the next step.
To give a more concrete example, SproutCore uses something called views for building interfaces. They are basically classes representing different types of UI elements. Having read the tutorial, I’m filled with questions.
- How many different kinds views are there? I suppose I’ll have to go trough the reference looking for classes ending in -View.
- What do they look like? There’s a demo page, but all the class names aren’t listed.
- What are the semantics? If there’s a list view and a scroll view, does this mean lists don’t scroll by themselves?
- How can they be nested? Can I put, say, a toolbar in a modal panel?
- What are the rules regarding sizing? The tutorial casually mentions that some attributes are derived implicitly.
You get the idea. I’m sure the the answers are somewhere, but finding them is a needle-and-haystack job through disorganized posts and mailing lists.
This isn’t to complain about SproutCore specifically, the same issue exists in many other projects. (Drupal, I’m looking at you.)
There seems to be a force driving documentation to two opposite poles. On one hand, developers feel a duty to document (but not necessarily explain) their code. On the other, well-meaning people write the very lowest level of documentation – over and over.
So, what can be done? The one thing I’d like to see is more articles on how to get specific key tasks done. Resist the urge to write another “getting started” tutorial that touches on a little of everything.
The author promises to write some useful documentation for an open-source project in the next week.