Why RTFM Won't Work: Documentation As Narrative

It never really worked - and not because there hasn't been some great documentation out there. Think O'Reilly for starters.

The problem has been the nature of software itself.

Even before the hyperlink, software was inherently multi-textual or, if you will, multi-task-tual. Task-centered documentation recognizes implicitly that we must isolate linear human steps within a far more complex, intricate .... web ... of functionality.

Heck, when Microsoft Word can't be documented because it is an entire world - kludgy, overgrown, messy but nonetheless a world - of scripting-augmented authoring power, you know that linear documentation not only never worked but that it surely won't work in the future.

A Community's Story About Itself

'Real' documentation is narrative - the accumulated lore of a community passionate about its tools.

It doesn't matter whether the tool is Doom, Word, Python or Radio.

By narrative, I mean that documentation accumulates as a community story about a product's use and use-anticipation (call it vision for enhancements) over time.

The vendor's documentation is, in some respects, the least interesting part of the equation. While the decade-long abandonment of serious vendor-produced documentation reflects some nasty and short-sighted business decisions, it also acknowledges - intuitively - that the best stories about the work of developers are told by their users.

This frustrates folks who haven't grown up playing Civilization II-and-its-discontents. Describing software, let alone documentation, as a game-like, communal activity makes the suit-and-tie set grind their teeth in rage.

"You mean I have to spend even more time with these damn computers?"

(Yup. Now does anyone remember when the suits were playing Visicalc as though it were Pac-Man while days and weeks fled by?)

In a fashion never anticipated even by the Seymour Papert's of the world, we are all playing lego-like with logo-like languages - or don't Doom, Word, Python and Radio each constitute an authentic linguistic phenomenon?

(I say this soberly, not for some witty, post-modern effect).

Spiral Rather Than Circular Documentation

Now, take the foregoing and conceive a product whose very design motif is community collaboration through published writing: Radio.

How can such a product be documented except ... collaboratively?

The last thing I want to do is baptize mere chaos as meaningful documentation. There is a world of difference between a community that is able - how? - to bootstrap its knowledge in spiral, rather than circular form. If users have to ask the same question repeatedly because we can't trap, store and retrieve that knowledge - say, "how can I manage two blogs at a time in Radio?" to name one minor query - we won't have documentation but just tedium.

The game becomes more fun as the narrative grows richer.

(Isn't this why Radio is more fun than Manila is more fun than Frontier is more fun than More is more fun than ThinkTank?)

For the narrative to grow richer, it must be accessible and amenable to enhancement alongside the software itself. While not everyone is a self-conscious documentor of Radio, nor should they be, this narrative requires a higher measure of intelligent participation than earlier ones.

Otherwise, RSS, XML-RPC, SOAP, OPML and the rest will remain mere acronyms rather than enablers of something resembling online community.

I am not sure what intelligent participation means. If this essay is mere hand-waving, let's toss it. But, surely, it must and can mean a process of cooperative logging, directory-building, rating, referring and dialoguing about Radio and - ideally - the creation of a few useful tools for the above.

Much of this is happening across a wide set of Radio weblogs already but we don't know yet how to mix the serendipity of cross-references with explicit map-making. Vannevar Bush remains prescient but we're a bit closer to real trail-making. Did someone say, "an inch at a time"?

A Conversation Between Vendor and Community

Seen this way, documentation becomes a conversation - a narrative, again - between the vendor and its user community.

For sure, such documentation is only documentation about Radio.

Or, to put it another way, it is the narrative of a single community and probably not the most interesting one. Radio itself can enable documentary narratives that are not product-centric but affinity-centric - between communities of journalists, doctors, lawyers, students, family and friends.

But it stands to reason that the best way to enable these communities - who will (and should!) have limited interest in Radio introspectively except so far as it is transparent to them - is to build a world-class narrative about Radio itself. For all communities except one, Radio should disappear behind the scenes.

Those of us who are picking-and-pulling at Radio are - or should be - the Radio 'manual'. So, let's write as well as 'Read The Funny Manual' to each other.

What?! RTFM doesn't mean Read The Funny Manual?!

Ah. Oh.

 <-- Return to Home Page