Comments on: Principles for Organizing Print Material [Organizing Content #21]

By: Sarah Biddle

Sarah Biddle — Mon, 25 Oct 2010 13:26:17 +0000

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?

By: Scott

Scott — Tue, 10 Aug 2010 04:31:56 +0000

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.

By: Kathy Wellisch

Kathy Wellisch — Mon, 09 Aug 2010 20:07:57 +0000

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.

By: Tom Johnson

Tom Johnson — Tue, 03 Aug 2010 16:29:19 +0000

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.

By: John

John — Tue, 03 Aug 2010 15:22:01 +0000

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.

By: Betty

Betty — Mon, 02 Aug 2010 22:47:13 +0000

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.

By: Scott

Scott — Mon, 02 Aug 2010 15:07:26 +0000

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.

By: Tom Johnson

Tom Johnson — Sun, 01 Aug 2010 01:20:04 +0000

Interesting idea. I hadn’t thought of the idea of a natural flow of content. Thanks for the insight.

By: When you need help, where do you go first? « Write Trends

When you need help, where do you go first? « Write Trends — Fri, 30 Jul 2010 20:31:18 +0000

[...] Patty @ 4:31 pm A thought-provoking tech-comm discussion is taking place right now over at Tom Johnson’s blog and got me thinking (told you, it was thought-provoking)… how many of us actually use [...]

By: Larry Kunz

Larry Kunz — Fri, 30 Jul 2010 20:14:14 +0000

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.