Principles for Organizing Print Material [Organizing Content #21]

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

Adobe Robohelp Madcap Flare

This entry was posted in findability, general on by .

By Tom Johnson

I'm a technical writer working for The 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS or by email. To learn more about me, see my About page. You can also contact me if you have questions.

25 thoughts on “Principles for Organizing Print Material [Organizing Content #21]

  1. Patty Blount

    Just when I think you can’t possible out do your last post, you prove me wrong yet again.

    This particular post is so timely… My org is currently in the middle of a significant shift from waterfall to agile and from PDF to web 2.0 delivery. I’ve been sort of “stuck” – an outdated analogy, but it works: a needle caught in the vinyl’s groove. I struggle to stop thinking in book terms because it seems clear that customers want other communication formats – web, wiki, social networks, etc.

    This sort of connects to our exchange some months back re: If users don’t read manuals, that’s NOT okay… the information is still essential but I agree, encyclopedic tomes are not going to be read, not in a society so excited by 140-character tweets, instant messages, and texts.

    Thanks for yet another compelling piece. I’ve already forwarded it to my entire team.

    1. Tom Johnson

      I was actually re-reading your post about it not being okay if users don’t read the manual as I wrote this post. Thanks for writing that, by the way.

      Re the explosion of information delivered via social networks, I think it does make it more problematic to package all that information up into a printed guide. Can you imagine stringing 100 tweets together into a printed guide and expecting it to be a good read? That’s why I say the organization of printed material has to be somewhat different from the organization of online help.

  2. Larry Kunz

    Nice article, and very well thought through.

    I’m not completely comfortable with one of your principles: “Material in a printed guide should be more conceptual-based than task-based.” Yes and no. I think it’s safe to say that most people are anxious to start using the product. So maybe they’ll read a couple of pages of high-level concepts, but that’s about it. Then they’ll want some tasks to get up and running. After that, they might never return to the printed documentation again.

    Additionally, the printed guide still needs to be searchable — meaning that you need running headers/footers, perhaps tabs, and — most important — a good index. At least, it seems that way to me. Do younger readers regard those things as museum relics too?

    1. Tom Johnson

      Thanks for your feedback, Larry. I didn’t mean to imply that the printed guide should exclude task-based material. I do include task-based topics in the printed guide. But I lead off with and include a lot of the concept-heavy topics, since most users reading the printed guide will be brand new to the product.

      Re the other aspects of a printed guide, headers and footers and tabs are mostly design elements, so they would also be included of course. But the index is controversial. It is a good idea to include, but if the guide is short, the table of contents mostly serves that purpose. In fact, many users refer to the toc and index interchangeably.

    2. Larry Kunz

      Tom, I think — check that, I know — that I’m biased in favor of indexes. So I have to admit that you’re right: For a short book, an index isn’t going to be useful. People will browse the TOC or, like the young lady in Alan Porter’s recent Intecom article, they’ll just skim through the book.

      So the emphasis shifts from overt organization to something more subtle: creating a “flow” that anticipates the way in which readers will approach the material.

  3. Paul K. Sholar

    I fear your suggestions are far too categorical. They just don’t work for a product with a really large body of functionality or features, such as an operating system (Unix, Windows, or Cisco’s IOS). There are plenty of products–within the computer field and beyond–for which it’s simply not practical (cost of printing multiple volumes, user struggles to organize so many physical volumes) to partition all the relevant content into 50-page chunks. And there are plenty of full-featured software applications for specialized fields whose documentation would appear “fractured” if divided into 50-page pieces.

    For a product with a large set of features, the writer must ask him/herself how *integrated* versus *modular* are the respective clusters of features–that is, to use a given feature cluster, how much must the user know about any other feature cluster. A large product with more integrated feature clusters requires that the writer recapitulate more information when describing each cluster, with the opposite being the case for a large product with more modular feature clusters. When a set of related and integrated feature clusters can be presented in the same physical volume, the user benefits from the convenience of being able to flip a few pages to refresh his/her memory about relevant content.

    Partitioning of content across multiple printed manuals should be a question of *user task*–that is, which tasks and subtasks are related in such a way to lend themselves to being described *conveniently* in one physical volume. Obviously it’s the word ‘conveniently’ here that’s the rub, and it can require the experience of several large documentation projects to clarify for the writer all the relevant factors that can be involved in making decisions about partitioning a large body of content.

    I disagree with the notion that task topics should be relegated to online help. Again, this is a question of how user tasks relate to each other and about how much supportive “context” content must be provided for the product’s task clusters.

    Another issue is that online help can be inconvenient to use due to the target computer’s screen size. While I’m working with features in this product that are new to me and thus must rely on task assistance, if the product’s own screen layout is such that opening an additional window or panel to view online help (which itself might be either extensive or require its own considerate screen “real estate”) interferes with viewing the product’s behavior, I’m going to be less productive and maybe even frustrated while. I’ve rarely found it to be inconvenient to place a printed manual near the screen so that I can follow printed instructions–that is, as long as the procedure to follow isn’t too long, such as around 10 steps–a longer procedure is a sign of a product design flaw and should be addressed early on with developers. Some user assistance requires that diagrams or other visual aids be presented to the user, which can preclude being effectively presented on the screen while the product is being operated.

    Paul K. Sholar
    Twitter: @BkwdGreenComet

    1. Tom Johnson

      Paul, thanks for leaving your comments. I have never written a manual for an operating system, so perhaps one really does need a 400 page tome for the user. Most of the applications I document are small and somewhat lightweight, rarely exceeding 200 topics in an online help file.

      One of the problems with printing large manuals is that users tend to keep the manuals around, and assume that they’re still valid even months after the application has been updated. I routinely ran into this when I delivered lengthy printed manuals to users. They would open up an outdated manual and be confused when the instructions weren’t accurate. The larger the manual, the more likely the user is to bind it and treat it like a timeless book. Since software development is trending towards agile processes, which means constant updates, the printed manual model doesn’t fit. The manuals will be hopelessly out of date months after their printing.

      By keeping the printed manuals short, conceptual, and focused on task basics (I didn’t ever say that I exclude all tasks in printed manuals), you have a better chance that the printed manual is still relevant a year later.

      On another note, I know bookstores that sell computer books have full-length manuals spanning 200 to 300 pages, and it maybe you can follow along by propping the manual up beside a computer screen. But I have to admit, anyone who is cool enough to have to learn a software app robust enough to require a tome rather than a pamphlet probably has 2 monitors anyway, or is savvy enough to prop up the help window on the side. Also, I don’t think the tome model fits the majority of users. But again, situations vary, which is why I had a disclaimer section. It may be that the long manual is the right fit for what you’re documenting and your audience.

  4. LU YU

    The manual in your photo looks like a motherboard user guide (multi-language version) from ASUS. I produced some of these stuff 4 years ago.

    Localized hardware manuals in print are required by most countries and regions and there is a saying at ASUS tech pub “no manual, no sales”. Besides, disclaimers against harm and loss caused by inadequate handling when doing DIY are important tool for customer service guys handling complaints.

    However, the reason to keep printed manual short is not from user’s perspective, but from the cost of printing. 5k copies is considered minimum PO, while an extra page can ruthlessly cost 4 sheets.

    1. Tom Johnson

      wow, you are perceptive about the photo. I just took that photo this morning because it seemed like a short-looking manual that demonstrated my point about printed manual length. It is an ASUS manual. It’s also translated into about 4 different languages, so it’s much shorter than it actually seems. I honestly didn’t think anyone would recognize it.

      Thanks for adding the point about the cost of printed manuals.

  5. Nina

    Nice post. When I first started working at my current company three years ago, they published a printed manual and shipped it to every customer. While I wasn’t able to convince them to let the tech writers write online help (don’t get me started on that), I did convince them to publish the manual as a PDF, available on the software CD and online, and to do away with the “paper-manual-for-every-customer” model.

    This saved the company some money, but a very vocal minority of customers complained. The company now sends paper manuals, on demand, for a fee. (So then the customers complained about the fee … you can’t win!)

    While I’ve made some headway on moving our help resources away from paper and more toward online help (using a tool like RoboHelp), part of the struggle is that those customers who actually want a paper manual are particularly vocal. And when it’s the visionary tech writer (ha ha) against vocal customer feedback, the tech writer loses.

    Since we are in a PDF manual compromise, I’ve been thinking of cutting 40 pages from our 350-page manual and having a “Getting Started Guide” that is separate from the nitty-gritty, step-by-step documentation that takes up most of the rest of the manual. Not an ideal solution, and I’m going back and forth on whether it’s worth the effort–if people aren’t going to read the 350-page manual, are they going to read a 50-page additional manual?

    Anyway, just wanted to say I enjoyed this post and find it very relevant to my situation. Thanks also for the links to related topics–I can add some of these to my arsenal for the next time I voice my desire to move away from a great big manual, and to use online help as our primary resource for clients.

  6. Paul K. Sholar

    Think about writing documentation for power plant-control software. The screen is dedicated to showing only one or another view of the plant and any alerts that occur as the plant runs. (No help panel will ever be seen.) How would you do it?

    1. Tom Johnson

      In situations where no help panel or window will ever be seen, then yeah, generate a printed tome for the user. But that situations is less common and not intended for the principles I described. I know it demonstrates a bias to talk about documentation as if it always describes software on a computer screen, but that has been most of my career. If you’re assembling something with physical pieces, if the device is too tiny to display help, or if there is no way to display help, then yes, print off a giant manual. But in the other 80% of the cases, where these exceptions don’t apply, I’d say make the printed manual short and put the rest of the content into the online help.

  7. Anoo Shaker

    Thanks for a great post, Tom!

    I agree that short printed matter like “Getting Started Guides” and “Quick Reference Guides” would be read more often than bulky “encyclopedic tomes”. Especially because there is the added advantage of quick updates and reduced costs . Printed communication pieces should be designed differently from online help as they do provide an opportunity to present “the big picture/bird’s eye view”.

  8. Karen Mulholland

    Great insight about leaning toward the conceptual in the print version and tasks in the help – I hadn’t thought of it that way but it makes sense. I think you’ve nailed it. Again.
    BTW, congratulations!

  9. Ben M

    This discussion illustrates to me why you need professional tech communicators working on this stuff. The project manager, the developers, whoever else—they don’t take into account all of these factors that affect the approach you need to take with your documentation.

    When I was teaching myself FrameMaker 7.2 in college, I had to consult the help for some things. When on one occasion I couldn’t find my answer, I looked over and saw a FrameMaker manual on the shelf in the computer lab. Hopeful, I looked there, only to find that the manual had the exact same content as the help system. I wasn’t happy, and this is the main reason I’ve been against pushing the same content out in different media. Different media have different purposes, so the content should reflect that.

    1. Kathy Wellisch

      Perhaps one of you could clarify your views for me, because I disagree that “Different media have different purposes.” I think that regardless of the output format, the purpose is the same: to provide the information the user is looking for as quickly and easily as possible. (Of course I recognize limitations to that – quick starts and reference guides have their place. However, these are discrete and time-sensitive topics. I’m assuming that you are referring to “the help” in general.)
      It seems implicit in your statements that the user must be looking for different information when he looks in either one or the other, but I think that is a faulty assumption. Why would I expect more – or less – information depending on where I looked?
      Why not use an html page to provide conceptual narrative? Use it to create hierarchy and context. Why should this be specific to a print version?
      By changing the information contained in the print help (vs. the online help), it seems like you are redefining what a manual is without necessarily telling the user that you’ve done it. You’re changing the delivery of information without changing users’ expectations. I don’t necessarily have a problem with shorter printed help, but the user needs to know up front that it’s not supposed to be comprehensive (and where to go for more).
      My own disclaimer: We never distribute in print, so it’s not an area where I have much experience. We distribute in pdf and html/xml. Nor do I have much experience with DITA, so perhaps my understanding of the structure you are using is faulty. I’d appreciate any clarification, though.

    2. Scott

      Kathy, you make an interesting point. I think what some of us are trying to say is that users’ expectations ARE currently that a printed guide will be short enough to consume in one or two sittings, and that more comprehensive reference material can be accessed elsewhere, for instance through the HTML help you talked about (where they are not required or expected to read every page front to back).

      And for all intents and purposes, PDF = print. Yes, it’s an electronic file format, but it is a format that is laid out for printing on standard pages and cannot include video etc., so it is basically a print format whether the user decides to use physical paper or not.

  10. Pingback: When you need help, where do you go first? « Write Trends

  11. Scott

    I think the question of how to organize a print manual can be answered by deciding whether it makes more sense to write a REFERENCE document, or a GUIDE document.

    A printed guide (more of a conceptual, introductory document) should definitely be shorter, flow coherently between sections, and have an easy-to-grasp table of contents.

    A printed reference document, however, such as a troubleshooting manual or listing of all available reports/features/code tables etc., doesn’t need to flow as easily and it can be as huge as necessary because both author and reader realize that the reader is going to jump to the relevant section, read a small portion, and put it down.

    So in that sense I don’t think all print documents need to be short, just the ones that you’re expecting someone to read through cover to cover.

  12. Betty

    I really appreciate your observations also. I think in getting rid of printable user documentation, we’ve done a disservice to the learning process. I know for myself that I need overview, big picture context when learning something new and complex, and I prefer to read offline when learning. As you say, the Getting Started Guide could just be another PDF online, but the flow would take you from overview concepts to basic tasks and then point to the detailed tasks in the online help. A printable book-like format with chapters or sections is much better for this than online help. It reminds me of an ebook, and people love to read them.

  13. John

    Some interesting points here, but I have to fundamentally disagree with one of your statements. You said, “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.” WHY? That is surely an incredibly lazy thing to do. Even with online help, topics can be grouped in a logical way to help the user see the relationship between them, especially for related functions. Sure, the user will still search and graze, but if they look at the topic grouping after finding a topic they need, they can see related items without having to guess what words you might have used in your writing.

    1. Tom Johnson

      Thanks for your comment, John. I do agree that you can provide more findability with help topics through related topics and other types of relationships. But ultimately, if the help file is large, online help files are non-sequential, non-linear reading experiences. They don’t lend themselves to a logical arrangement other than general folders to try to group similar topics in.

  14. Sarah Biddle

    That’s the ‘problem’ of single-sourcing: it hides the intrinsic differences between the media you use as output. It makes you focus solely on content and less on form. Sometimes I wonder whether single-sourcing offers much benefit. Is it smart to force language into rigid XML-tags?

Comments are closed.