Alan Brandon

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?

Here’s a cool picture from the IEEE’s 125th anniversary photo stream on Flickr.

What are those people doing? It looks like they’re reading. What are they reading… wait are those manuals? Printed manuals! How old is this picture anyway?

The  Institute of Electrical and Electronics Engineers (IEEE) turns 125 years old this month, and I want to give a shout out to the organization that has been a big part of my career as a tech writer.

The IEEE turns 125 this month

The IEEE sets the standard for, well, standards. According to the IEEE they publish about 30 percent of the world’s literature in the electrical and electronics engineering and computer science fields and have a portfolio of nearly 1,300 standards and projects under development.

Some of the IEEE standards I have worked with over the years include:

• IEEE 802.3 — Ethernet networks
• IEEE 802.11 — Wireless networks
• IEEE 1394 — Serial bus known as “FireWire” and “i.LINK”
• IEEE 488 — Standard Digital Interface for Programmable Instrumentation, formerly known as GPIB and before that as HPIB.
• IEEE 1284 — Parellel port

I just rediscovered John Hewitt’s excellent PoeWar blog, and I found a great article about trainers as a powerful resource for tech writers.

If you want help creating documentation, get to know the trainers. I am frequently amazed at how little communication some companies have between the training and the documentation departments. In many cases, the training departments develop their own materials…. More than once I have sweated over creating a procedure, only to find out later that it was already in the training materials.

Trainers not only get to know the company’s products, they get to know the customers. For many (shortsighted) companies, the trainers are the closest thing you have to a usability team. They walk through the product in front of the clients, who inevitably have questions about the process or come up with scenarios that point out the limitations of the product.

Hewitt’s opening paragraphs reminded me of two recent gigs, and the contrasts in their relationships between the trainers and the writers.

At one company, the tech pubs manager arranged for a special training class just for us writers and editors. The entire department attended and we had a custom presentation about the upcoming release and the overall product line. We got to pepper the trainers with our particular writer questions about the customers and how the docs were really used (or not used).

At the other company, a large corporation with a broad product portfolio, we were essentially denied any chance to interact with a trainer at all. The company had an extensive “university” with many training courses and instructors that traveled to the various corporate campuses. Unfortunately our department policy only allowed us to take courses that were free. All of the live training classes had a cost associated with them. But these were internal, inter-department charges. The money didn’t leave the company. Nevertheless we were limited to watching prerecorded tutorials or narrated PowerPoint decks with no opportunity to ask questions.

At the first company I was able to hit the ground running with a good view of where my project fit into the company portfolio and into the overall customer experience. At the second company, it was much harder to know how the features I was writing about were relevant to the customer.

The microblogging service Twitter is experiencing monster growth. It’s great for keeping in touch with your friends and fans, but does it have any use in tech writing? Paul Pehrson discusses this in his recent blog post, “Twitter and Tech Communication“:

I’ve seen several Flare users get product support from MadCap employees using Twitter, and I think that is nice for a quick question with an easy solution. Twitter, however, is not a great format for a detailed question that required specific examples and detailed answers. In such cases, the best solution is probably to go to a related email list or forum where you can ask the question in enough detail that experienced users can provide helpful results.

Twitter can be a great tool, and can help people get answers quickly. However, when you have a question and need an answer, you probably ought to consider your question, and determine what channel is best suited for the type of answer you need. That may or may not be Twitter.

Pehrson focusses on Twitter in a customer support role. While complex answers won’t fit in Twitter’s 140-character limit, a tweet is an excellent “RTFM” vehicle. Just like the live chat some support sites offer, Twitter lets a support rep send the customer a link to the information they can read on their own.