Form and function, revisited

26 Oct

Posted by Scott as advice, authoring, documentation

aesthetic A while back, I discussed this topic in a bit of detail. Something that happened recently made me want to return to this topic.

While preparing for an upcoming presentation, I was hunting through one of my notebooks for a bit of information. You probably know the kind of search I mean: that quote or snippet that you can’t quite remember or remember where it is, but which packs a meaning or a message that’s useful for what you’re working on. In that notebook, I stumbled across something Adam Hyde of FLOSS Manuals told me:

Documentation has to have an aesthetic strategy. Documentation has to be consumable. It has to be friendly, not just in the way it’s written but in the way it presents itself. Publishers spend a lot of money designing books for this reason. I think that documentation should follow the same principles. It should be easy to read, it should look attractive, and it should look like something you want to engage with.

While I’m a firm believer in the primacy of content over appearance, there’s more than just a faint ring of truth in what Adam said. Aesthetics are definitely a part of drawing people into documentation and engaging them. There’s nothing wrong with making online assistance or a printed manual attractive. It doesn’t need to be a beautifully-designed work of art, but it should be something a little more than blocks of black text on a white page.

As I mentioned in a presentation that I did last month (in the context of using a wiki for documentation):

You’ll also have to make the wiki attractive to users. It shouldn’t look like a wiki. It should have something akin to the look and feel of your corporate Web site or the online documentation that the company has produced in the past. A good example of this, though not from the documentation world, is the official wiki for the TV series Glee. That wiki looks, more or less, like the rest of the Fox Web site and not like a wiki.

You don’t have to go overboard on this. Just something that’s a little more aesthetically pleasing than, say, the default look of a FrameMaker, DocBook, or DITA document.

The real key to creating a successful documentation is content. Giving readers the information that they want in the way they need it. The documentation should focus on how to do things. If the content doesn’t follow what I call the 5 Cs: