Interestigness in documentation

Draft

This draft is a work-in-progress.

Technical writers generally agree that accuracy and clarity are primary attributes of good documentation. Occasionally, they ask whether “beauty” is important too, but often dismiss it as a secondary or derived quality.

When I’ve been involved in conversations about beauty in documentation, I’ve noticed that people tend to discuss lofty ideas from architecture, literature, and classical music. It’s all very sophisticated, and a little perplexing.

The Bauhaus are invoked with some frequency, as if it is an unassailable truth that they were correct about buildings, but also that those same ideas map cleanly to documentation problems.

So there is an excessive utilitarianism — good documentation is just about stating the facts clearly — and also an excessive intellectualism — good documentation is like the great temples of antiquity, and not enough in between.

I prefer to think about whether something is interesting or not. A thing doesn’t have to be beautiful to be interesting, and beautiful things aren’t necessarily interesting. Interesting things make us curious. If you make something new and useful, it is more likely to be used if it is also interesting.

For most of us, it’s easier to produce something interesting than something beautiful. It’s reasonable to expect a teacher to give interesting lessons but strange to expect them to teach beautifully. I’ve met teachers who thought that it wasn’t their job to be interesting, but their clear and accurate lessons failed to engage students who then struggled to learn the material.

Writers of documentation may think that interestingness, like beauty, is secondary. Similarly, people think that nutrition is the primary function of food, and that sensory properties are secondary. But people reject nutritionally-complete meals when they are bland, and a meal that isn’t consumed never expresses its primary function.

When we divide functions and attributes into hierarchies, we can become unsystematic in our thinking, and lose sight of the necessary relations between things. A commercial food product must be designed with parallel consideration of its nutritional and sensory properties. A university course must be designed to be both true and interesting.

Despite being commonly used, the notion of interestingness never seems to attract sustained attention in the way that beauty does. Many human endeavors are built on the interesting. In science, we make observations of interesting phenomena then seek to attract the interest of other scientists, funding bodies, and the broader public. It might be possible to publish scientific papers with uninteresting findings, and attract the interest of nobody, but that is not a recipe for a successful scientific career.

Interestingness sits somewhere between salience and beauty. When we can discriminate something against a background, it is salient. An example is a tree in a field. But for something to be interesting, it is not enough for it to be salient. It must also be sufficiently different from the class to which it belongs. A tree engulfed in flames is interesting; it’s a lure, it steals our attention, and we wonder about it. How did this happen? Was it intentional?? Can I spot the arsonist??? Was it lightning???? Should I tell somebody????

When we write documentation, it has to be interesting to someone. A page must be worthy of attention and warrant reading. A person doesn’t know that something is accurate and clear until they read it. When they encounter a page, they decide whether it is interesting enough to read. If quality is measured by the ability of someone to successfully navigate the content, then failure can be an inaccuracy that leads them to error but also a page so uninteresting that they never get started.