Single Sourcing and Redundancy

Although we have a lot of single sourcing tools, and the term single sourcing is used constantly in tech comm conversations, I’ve never had a firm answer to the following question: How should the print output differ from the online output?

Let’s assume that you have all your content in a help authoring tool. You have two outputs configured: an online help and a PDF manual. Should the two formats contain about the same content?

This question isn’t as relevant with some platforms, such as wiki-based platforms. With MindTouch, for example, users can choose to create their own table of contents and render it into a PDF on the fly. Other browser-based platforms, like Mediawiki, may keep all of the content in online formats only.

However, if you’re using a help authoring tool, such as Flare, Robohelp, Author-it, Doc-to-Help, or some other tool (such as DITA Open Toolkit), you’re often presented with a variety outputs to choose from. Generally you store your help content in the help authoring tool and publish selectively and strategically to the outputs you want. But the strategy about what should you publish to each output tends to be something that gets overlooked.

You can publish to both outputs with varying degrees of redundancy. I’ll explore four basic options.

Option 1: Full Redundancy

One option is to keep the online help and printed guide pretty much the same. Sure, the PDF has a title page, table of contents, and maybe an index. But there’s not a whole lot of difference between the printed guide and the online help. The content is redundant between the two mediums. Users choose the medium they prefer.

Full Redundancy

Option 2: Partial Redundancy

Another option is to publish a subset of the topics to one output, usually the PDF manual. Your online help might be a giant repository of all kinds of content, as you write for the long tail. But the PDF manual would only be a fraction of the total information. The printed guide just contains the mainstream tasks and concepts.

Partial Redundancy

Option 3: No Redundancy

A third option is to make the PDF manual substantially different from the online help. Proponents of this camp believe the scenarios for which people access the online help versus the PDF vary significantly. Because of the different scenarios, the formats warrant entirely different content.

For example, I’ve heard people say, “If it’s in the online help, why would users want to view the same content in a PDF? Wouldn’t users want to see the information presented in a different way? Otherwise, if the content is the same, what’s the point of having a different format?”

No Redundancy

Option 4: No PDF

A fourth option might be to dispense with the PDF altogether. When you have help online, do you really need a printed guide? Printed guides get quickly out of date as software changes, especially in agile environments. When users download and print long manuals, and then bind and shelve them for reference, these outdated manuals become a liability. If you have a web-based platform where you’re authoring and publishing content, you might just stick with one source.

One Output Only

My Analysis

Let’s break down the question by analyzing in depth why people would access both formats. In general, advanced users (users already familiar with the application) don’t print guides. If you already know the application, there’s little reason to print off the full manual or even read the help. Instead, advanced users usually search the help for answers to specific, often difficult questions.

The printed guide mainly serves the new user. You don’t want to bury the new user with a ton of information, so you probably would select Option 2: Partial Redundancy. The printed guide could be enough to introduce new users to basic concepts and tasks to get them started. You can add references to the online help for more advanced information.

With this strategy, the emphasis of the printed guide would be more of an introductory guide, with the assumption that users have limits to the amount of new information they can process. Sure, users can print a 700-page guide and plan to read 50 pages a day for the next two weeks, but most likely the user who prints a 700-page manual will die of a heart attack as he or she watches the printer print page after page for two hours straight.

Writing for the Long Tail

Earlier I used the phrase “writing for the long tail,” but I didn’t explain what I meant. By long tail, I’m referring to the non-mainstream help topics. Usually technical writers aim to cover topics of interest by the majority, the 80% rather than the 20%. Usually people assume that the 20%, the non-mainstream topics, aren’t worth including since they’re used by so few.

However, Amazon.com found that doing well in the long tail game proved more successful than sticking with mainstream products. The aggregate sales of the non-mainstream products adds up to sales greater than the mainstream products. In other words, you may only sell one Grateful Dead coffee mug, one Nicki Minaj wig, one lizard-skin wallet, one Jerry Mumphery rookie card (who’s he?), and one used hubcap, but when you keep adding up these odd sales, they begin to outperform the Disney DVDs and other mainstream product sales.

With help content, if you write for the long tail, you choose to include the non-mainstream topics that might not otherwise fit into a guide. Think of all the knowledge base articles that get written by support center agents — the advanced technical notes, the  information about bugs and workarounds, specific scenarios for ad hoc roles, situations specific to particular languages or regions, and so on. Each topic may get only 25 hits instead of 2,500, but when 1,000 people each click the topics, their aggregate traffic exceeds the mainstream.

Usually the long content doesn’t fit well into help material. But where should it live? About the only place for long tail content to thrive is online. If you include all the miscellaneous information into a PDF manual, users will scratch their heads about why you included so much seemingly random, category-resistant content. It doesn’t fit the book-reading paradigm that values sequence and order.

As a best practice, I think it’s good to include the long tail content online, either with the online help or on a connected site, and let the user search to find and retrieve the topics. But don’t single source all this long-tail content to the PDF manual. Let the PDF manual stick with the basics, targeting the new user who is learning the application. Keep the PDF readable in an attractive way.

I’m curious to hear what your practices are with redundancy between online and print outputs. Which option (if any) do you follow?

Adobe RobohelpMadcap Flare

This entry was posted in findability, general on by .

By Tom Johnson

I'm a technical writer working for a gamification company called Badgeville in the Silicon Valley area in California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), content development (DITA, testing), API documentation (code examples, programming), web publishing (web platforms, Web design) -- 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.

21 thoughts on “Single Sourcing and Redundancy

  1. Donna

    Watch out for a more granular boo boo; I inherited a document with full redundancy.
    Usability in online Help topics = stupid redundancy on the page.
    The same phrase appeared on the same page and within the same chapter multiple times, such as “See these related topics…” with a list of the same related topics.

    The logic defending this was, “We don’t know where the reader will encounter the information.” That’s exactly why it makes sense for Help and other online formats, but we can safely assume readers encounter PDF pages in almost a single glance.

    (I won’t even mention the “User Guide” I was shown, in printed format, that said, “Click here.” Oops, I mentioned it.)

    1. Tom Johnson

      Donna, you bring up an excellent point. I want to explore redundancy within the same deliverable at some point. I’ve heard the same argument — design for a reader to enter at any point. The problem occurs when you break the content into units that are too small. Then you have to start repeating yourself or adding a ton of cross references. Here’s where the Every Page Is Page One style comes into play. Make the topics substantial enough that they can stand on their own. Chances are you won’t have as much need to link out or repeat the same content.

  2. Pingback: What is your primary media? - Every Page is Page One

  3. Mark Baker

    Great dissection of the issue, Tom.

    But I think there is another question that needs to be asked first: which is your primary media? Which media do you design for as your primary? Until you decide if paper of the Web (or help) is your primary, you can’t really decide which content should be in which media. More about that here: http://everypageispageone.com/2013/02/04/what-is-your-primary-media/

    On the issue of the long tail, I think it is important to point out that the long tail of information on your product is not just the low-volume content you produce yourself, it is all the content about your product that people create and share on the web. Your long tail strategy should probably take account of this, and look at where in the long tail you can provide the most value. You can’t cover the entire long tail yourself — it is far too long a tail. So it makes sense to focus on covering those parts that are not being covered by others.

    1. Tom Johnson

      Mark, you are brilliant as always. I enjoyed reading your post. You said, “Content designed to be read sequentially will never work as well when accessed at random. Content designed to be accessed randomly will never read as smoothly when read sequentially.” I agree that we have to choose a primary media to design for, and that the Every Page Is Page One topics work pretty well in print anyway.

      I do think that the linear, sequential nature of print invites a different writing paradigm, but not one that is necessarily feasible for tech comm.

      By the way, long ago I did explore a similar topic, some 50 posts earlier in this series: Principles for Organizing Print Material [Organizing Content #21].

      I have a feeling I’ll address this topic again in the future…

      1. Mark Baker

        Thanks Tom. Just read the post you pointed to, and I pretty much agree with all of it, provided, at least, that the online content is actually usable, which, alas, is not a given always.

        It was certainly assumed in the early days that the print docs had to be complete and the help was supplementary. Today I think it is safe to state as a principle that the online information must be complete.

        In fact, I’ll broaden that into a more general principle: if you provide a search box, it must search everything.

        No reader today will accept the notion that a search box does not search the entire domain. If their search returns no answer, they will assume there is no answer.

  4. Tammy

    I agree- great analysis. I think there is another issue to keep in mind that Donna touches on some above – what differences should there be because of the format/presentation? Screen shots that make sense in a PDF may not make sense online, or you may have more space in one format than in another. Donna already mentioned some strategies that work online that may not work in a PDF. Efficiencies for the writer need to be balanced with usability for the user.

    1. Tom Johnson

      I know a lot of people omit screenshots from the online help but keep them in the PDF. The assumption is that the user is looking at the screen online and doesn’t need screenshots. I’m not entirely convinced by that argument, but I can agree that the two formats aren’t the same. They merit different strategies. At the same time, that’s a lot more work.

      1. Mark Baker

        Online, you have the option to make the display of the screen shot optional.

        How much work it is to format the two differently depends entirely on how the input is structured. If the input uses markup to note when a particular dialog box is mentioned, for instance:

        Select File>New>Project. The New Project is displayed.

        Then you can have the algorithm that create the PDF output insert a screen shot of the named dialog box after a step that mentions that dialog box, and you can have the algorithm that creates the Web output create a link on the words “New Project” that will pop up a screen shot of the New Project dialog when the reader either clicks it or rolls over it.

        And, if your help system supports driving the interface from the help file, as some do (“show me help”), you can even have the help system actually open the New Project dialog box when the reader clicks the link.

        It is simply a matter of removing the display logic from the authored source and replacing it with the metadata needed to drive display logic on the back end. See: http://everypageispageone.com/2013/01/28/we-must-remove-publishing-and-content-management-concerns-from-authoring-systems/

      1. Mark Baker

        JoAnn Hackos has an interesting post on this: http://t.co/VtblqShs

        I had one client who insisted on PDFs, but when we investigated we found out that it was so they could search them, not because the wanted to read them sequentially. Problem was that the search available in the help system (Eclipse Help) was so abysmally bad that it was unusable.

        PDF is often the user’s fall back for an information system whose navigation and search functions are unusable. The answer is not to keep producing PDF, but to fix the navigation and search of your online content set. My prescription for that will surprise no one: Write in Every Page is Page One topics, and put them where Google can find them.

  5. Lynne Van Wagenen

    In our case, we output to PDF, sometimes online help (chm or javahelp), and to plain HTML that gets spidered in our knowledgebase.

    I add more more detail and more screen shots to the knowledgebase articles. Support agents want one doc that contains a complete answer. They want screen shots so that they can tell a patron hwere to find an option–without having to share screens or memorize every product they’re supporting.

    I filter a lot of the screen shots and some detail from the PDF, or it gets redundant and long.

    Putting a lot of screen shots in online help (CHM or javahelp) can make the content hard to view. So all but the most crucial get filtered out.

    Support agents also require different details than end users. You may tell a user to “contact support” for help with some issues. However, the support agent needs to know what to do when a patron calls with that particular question. Those types of details need to be filtered in and out.

    I think you do have to choose your primary media. If you optimize for PDF, I find that I tend to write shorter topics that rely on linking or proximity to get users to relevant detail. When I optimize for a KB, I write longer articles with more detail. The resulting PDF has a bit less flow, but it still gets users the information they need.

    1. Tom Johnson

      Hi Lynne. Your use case with the KB articles is a great scenario to explore. I can see how a support agent would need more info to troubleshoot an application he or she can’t event access. I remember creating a long document for a support center once that had — per the user’s request — a screenshot for every step.

  6. Jeanne

    A number of years ago (when the West was young), I performed a small usability study concerning non-redundant online help and printed product documentation (option 3 above). The online help provided UI-related task instructions (with links from the UI to the topics); the printed manuals contained reference info. (There were historical reasons for the division.)
    We set up the questions so both types of documentation were needed. Customers looked for answers in only one place OR the other, and were almost invariably frustrated because they could not find the “other half” of the information they needed. It did not occur to them that the information was not duplicated.
    The product we were testing was an established product and we could not fundamentally alter the documentation delivery methods. One thing we did immediately was add more explicit mentions in each doc set of the existence of “the other documentation”. Over the next few releases, we were able to add the reference material to the online help (turning our “mentions” into live links), and to create a PDF output of the online help. This allowed users to search the entire documentation set in either online help or PDF, and/or to print a version of the online help task-based topics, if desired (although it read about as poorly as would be expected from topic-based help printed serially…).
    If I were supporting a similar product now, I would probably opt for partial redundancy, with “new user” tasks available in a readable PDF, and the bulk of the information online, printable by page (or topic).

    1. Tom Johnson

      Jeanne, thanks for sharing the small usability study you did with the help. This is exactly relevant to the question I’m exploring here. I’m glad to learn that users expected to find the same information in both places.

  7. Cindy Fisher

    Our customers still ask us for both PDF and Web-based help, so we’ve tried to adapt and included conditional-text into our writing that, when published, some information will go to the PDF version and some will go to the Web-based version, or even a third way, the chm version. The CHM version has the least amount of screen shots, so as not to slow down our whole software system (although, I wonder if others have the same issue?).

    But I had an ah-ha moment the other day when I was trying to look up something on the Apple Web site. We’re always bad-mouthing our users who want PDFs. “People just don’t publish to PDF anymore.” Well, here I was on the Apple Web site, a company some of my colleagues revere as being the most up-to-date and cutting edge with all their technology, and my heart was overjoyed to see they were still using PDFs for procedural explanations.

    Additionally, we have one quirk in that our documentation on the Web can only be accessed from a secure site, after customers enter a username and security code. We could link to lots of extra information from our CHM’s to our Web site, and we do, but I wonder how many of our users take the time to enter their password and security code to access it.

    I’d like to have a frank discussion with our company president about not being so afraid of having our information under lock and key. I see our online manuals as a type of marketing piece. Does anyone else have proprietary documentation not easily accessible on the Web? Perhaps you could write another entry about that, Tom.

    1. Neal Kaplan

      Cindy: We had a similar setup when I started at my current company. What changed this was a discussion with someone in Sales, who pointed out that our competitors could (and did) create accounts in our system, and had access to all of our documentation. So why hide it? He helped me explain to the CEO that the could be used as a sales tool, and in many cases we were asked to create PDFs so that prospects could look at the docs.

      Now we have open docs, and I get comments from our sales team that they use them all the time to help answer questions from prospects, while our competitors hide their documentation. Actual quote from one of our sales engineers: “Do not underestimate the impact our Knowledge Center can have in a sales cycle. This is a huge differentiator in competitive deals. Every product, feature and use case is documented and transparent for the prospect to access.”

      We focus on delivering online (web-based) help, with the option to create PDFs. Now that our docs are open, I only get requests for PDF when one of our employees is traveling and wants some documentation that they can read while offline.

      1. Neal Kaplan

        That said, I do like the idea of an “introductory” PDF. We have some Getting Started material, and I’m going to have to think about whether that might be the basis for a nicely-formatted PDF that we could hand to new users.

  8. Diane Thompson

    I would have to say “Somewhat Redundant” although I really like the partially redundant example. We moved to DITA XLM and topic-based authoring with the intention of single-sourcing. We created topics, just like in the book, for tasks and references mostly for the online help. Then we added some concept information for the pdf version. With a ditamap, you can use the same topics but change the output order so that one is used for online help and the other ditamap is for the pdf.

    Most of the topics were exactly the same. Internal directory pages were left out of the pdf ditamap and concept topics necessary to the flow of the pdf were left out of the online help ditamap. This was an Adobe TCS 3.5 project so we had access to a pretty good TOC and Index. It was also used in a context-sensitive system. Oh, we had to provide paper document potential (pdf) because of FDA and IVDD rules. It is dicey but truly is single-sourcing.

Comments are closed.