Write your next manual in PowerPoint

There’s a great post on the DMN Communications blog about a new book from O’Reilly Media called The Twitter Book. The book, by Tim O’Reilly and Sarah Milstein, was written entirely using PowerPoint.

As Scott at DMN puts it:

So what does this have to do with tech comm? A lot, believe it or not. Each page is self contained. In most cases, you don’t need to read other pages of the book in order for that page to make sense. This approach is very similar to … topic-based writing.

Now, topic-based writing is one of those concepts that ebbs and flows in technical communications. I have seen a surge of interest in it lately, in the context of XML and structured documentation. But topic-based writing — sometimes unflatteringly called “chunking” — has been around for many years. When I was at HP, the official writing guide was based the idea that each “topic” was a standalone chunk of information.

Good topic-based writing is hard. In topic-based writing you have to carefully plan the structure of your information, which drives the structure of your document (book, help, etc). You also have to write succinctly and avoid going off on tangents.

Topic-based technical writing is easiest when you have a well-designed product to write about. (OK, all technical writing is easier when you have a well-designed product.)

Tim O’Reilly blogged about writing The Twitter Book using PowerPoint, the ubiquitous presentation app (emphasis is mine):

The web has changed the nature of how we read and learn. Most books still use the old model of a sustained narrative as their organizational principle. Here, we’ve used a web-like model of standalone pages, each of which can be read alone (or at most in a group of two or three), to impart key points, highlight interesting techniques or the best applications for a given task. Because the basics are so easy, there’s no need to repeat them, as so many technical books do. Instead, we can rely on the reader to provide (much of) the implicit narrative framework, and jump right to points that they might not have thought about.

You don’t see many technical documents about how to use a hammer or a light switch, because the basics are so easy. But a lot of users (the customers!) get frustrated by product documentation because it spends too much space covering what they already know and not what they need to know. How often have you seen technical documentation in which the first few steps of every procedure are: switch the unit on, make sure the cables are connected, etc. In the reader’s implicit narrative they have already done all that. They are looking for the next bit of information. The next topic. The next chunk.

O’Reilly discusses some of the reasons tha he chose PowerPoint for the The Twitter Book including ease of updates and speed. The entire blog post is worth a read. Will I be writing my next router CLI reference manual using PowerPoint? I doubt it, unless I get a really good hourly rate. For now I’ll stick with Flare and FrameMaker. How about you?