Sturm Und Drang IF: A Stormy Romance

The Inform 7 Documentation Fails as a Reference

November 1, 2010 at 6:51 am (Inform 7) (audience, documentation, structure, technical writing)

I have discussed other ways in which the I7 docs do not succeed here, in terms of tone and style and here, in terms of general organization and approach. However, beyond those offenses was buried an even deeper, systematic flaw: the documentation fundamentally misunderstands the audience.

Have you noticed that the actions that new things (objects, phrases, and so on) are often separated by several chapters from their modifiers and things that you customarily do with them? Worse, there are no cross-references (i.e. “For how to describe objects, see chapter 20″). This leaves you floating frustratedly, wondering where to turn.

Ordinarily, you would consult the Table of Contents. However, you can’t do that here, because it is vague, even in its single-level subheadings. How about the index? There isn’t one. Search? Search stupidly indexes every appearance of the word with no hit values or accuracy rating. So, you do what people did before such helps were created — flip through the pages randomly trying to figure out where the author has hidden the piece to the puzzle. Running over and over in your mind is this one question: “Where do I look next?”

Here’s the awful answer: you’ll never know unless you read the I7 docs straight through (if the answer is even provided). That is probably the worst structural offense of the documentation. It’s simply not written like a reference manual. Instead of helping people find what they want, the author has assumed that the reader is sitting in an easy-chair before a cold winter’s fire, sipping tea or coffee, with a cat curled up in his lap, languidly thumbing through the story of Inform. Yet, vanishingly few author/programmers behave that way.

Therefore, extracting information from the I7 docs is maddening. Whomever wrote these docs (and I suspect that I know who) should never be allowed to author technical documentation again. It is a crime against technical writing to turn out reference material written like a novel, and one could argue, a crime against literature as well. Nothing is worse in writing than missing your target audience; it is the literary equivalent of giving a boy who asks for bread a stone instead.

The structure assumes the direct opposite of what we know about technical audiences (little time; need to get information quickly). It further compounds this mistake by not providing helpful helps (cross-references, indexes, a meaningful search). Finally, it completes its worldview with its incomplete nature, providing a final irony: even if you do manage to slog through the whole thing, you still may not find the answer.

The Inform 7 documentation just might comprise the most effective case study in how not to write technical documentation ever written.