Search results

Principles for Organizing Print Material [Organizing Content #21]

Series: Findability / organizing content

by Tom Johnson on Jul 30, 2010
categories: findability technical-writing

For years I prided myself on single-sourcing both online help and printed guides. When I used RoboHelp, I created custom macros in Word to clean up and adjust the print formatting. With Madcap Flare, I hammered out the print styles until everything looked clean. And then I made a major mistake: I more or less single sourced the online help to the printed guide in a near 1:1 ratio.

One day a department manager told me he was preparing to give a presentation to new employees, and he asked me for the printed guide so that he could distribute it during the training and orientation. Sure, I thought. Because of the high visibility, I decided to print it out the guide and read it cover-to-cover to make sure I wasn't missing any typos.

The printed guide was about 175 pages. As I read through it, red pen in hand, I had two epiphanies. First, a lot of the topics didn't connect with each other in the seamless way you would expect from a print reading experience. This disconnect is probably the inevitable result of topic-based authoring -- topics aren't necessarily chronological, nor does one topic lead in to another.

Second, after reading 50 pages, I was done. I had hit my technical reading threshold. There's only so much instructional material I can ingest before it all becomes a blur and I simply need to play around in the application to continue learning. Perhaps if the material were more concept-oriented, I could continue reading far beyond 50 pages, but with step-by-step tasks, there's not a whole lot that one can internalize from just reading step 1, step 2, step 3, and so forth.

After this experience, I changed my approach to single sourcing. I no longer single source from online help to printed material in the near 1:1 ratio that I did before. For my printed material, I include only the basic topics, and I try to limit the printed guide to around 50 pages or less. The printed guide mostly serves as a primer for users who are new to an application. It's not intended for advanced users.

Printed manuals should be brief, because almost no one has the patience to read a 200 page manual.

I freely admit that a good majority of people bypass the manual altogether and simply jump into the application. I do this too. But in doing this, many times I get stuck, because the interface isn't as intuitive as I hoped, and so I turn to some instructional material. When I do turn to the help as a starting point, if the help is a gigantic array of folders and subfolders with dozens of topics arranged in almost no hierarchical or chronological order, as is the case with many online help files, I get lost. I want a clear path for ramping up in the application. The 50 pages of information in the printed guide helps get me started and going in a much more friendly way.

Some Disclaimers

Before I go too far with my dismissal of the extensive single sourcing that I previously adopted, let me point out a few disclaimers. First, this whole topic gets into the discussion of whether anyone reads the manual. The variety of software and different user scenarios makes it difficult to generalize trends. Everyone has an uncle who reads manuals cover to cover. Everyone knows a teenager who marks up his video game guide with an almost religious scrutiny. Everyone has a customer who needs the full manual printed out because they want to include it in a packet for new employees.

Ideally, I'd like to move beyond anecdotal evidence and point to researched trends, but I'm not sure the topic has much hard research to stand on. My perspective has mostly been shaped by the experiences I've had and by my own methods for learning software.

Relationship Between Online Help and Printed Guides

Now that I've made my disclaimers, I'd like to state a few principles:

  • Material in a printed guide should be more conceptual-based than task-based. This is because concepts align more closely with the book-reading experience. Users who sit down to read through a manual are most likely new to an application, so they need the conceptual, big-picture grounding rather than nitty-gritty how-to tasks. Concepts are also more readable than step 1, step 2, step 3 type of material.
  • Material in a printed guide should be relatively short. Readers should be able to get through the printed material in under an hour, which translates to about 50 pages of material in my experience. Many readers won't read more than 5 to 10 pages, and the degree of material users read depends on the number of graphics you include, the level of difficulty of the reading, whether you have descriptive examples to help move through the content, and so forth. But in general, keep the length of the printed guide short -- much shorter than the online help.
  • Organization of the printed material needs to have a different flow than the online help. With online help, you often add a jumble of topics into folders and assume that users will search for answers rather than move in a sequential way through the topics. But with printed material, the organization of topics needs to have more threading from one topic to the next. Topics can't be a disjointed jumble of this and that. They need to have more of a flow and a conceptual arc. Craft the table of contents order carefully, and then print out the manual and actually read it to verify that it has a seamless and pleasant reading experience. I usually like to start each chapter with an About section that introduces the concept, and then follow it with a few basic tasks.

Conclusion

Long printed manuals are becoming museum relics. If you're delivering a 200 page printed manual for your software, expecting that users will read it cover to cover to learn the application, you're kidding yourself. Reproducing  the entire online help in printed form for those one or two users who request a whole handbook does a disservice to the majority of users who prefer just a light print reading experience to get started. If your experience has been different from what I described above, please share your perspective with me.

Recommended Reading

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.