Get new posts delivered straight to your inbox.
Enter your email address
powered by TinyLetter
Jan 12, 2011 •
Last year I started a series on organizing content that spanned nearly 30 posts. I want to return to this thread with a summary of why findability becomes an issue for technical writers, and what the information paradox is that we encounter. Then, in an usual ethical twist, I'll explain why findability might not actually be an issue.
The help scenario starts out innocently enough. As a technical writer, I document the main tasks users can do in an application. I describe core features and how-to information.
But as times goes by, and I get deeper and deeper into the application, I learn more and more about it -- the not-so-intuitive processes, the workarounds, the edge cases, the unresolvable bugs, the usability problems. I transfer this information into the help file because information is my game.
When the app is released, I start to hear feedback from users through various means -- calls to the support center, questions during training, emails and conversations. I add much of this information to the help. In the back of my mind, I envision a day when all users can search the help for even the most arcane questions, the most unique situations, and they will find -- to their surprise -- the answer.
In fact, during one project, I even played a support role for the application. I made it my goal to never answer users' questions without pointing them to the answer in the help file. This would accomplish two things: (1) it would require me to supplement the help file with possibly missing information; (2) it would increase the user's confidence in the help. So phone call by phone call, email by email, I added more and more information to the help file until something strange started to happen.
The findability of help topics started breaking down. I reached the point where the help information transitioned from somewhat straightforward to definitely complicated. Each folder had a lot of topics, and some folders had subfolders and subfolders with a lot of topics. I began to forget where some topics were, since they overlapped topically with other folders. I knew that if I forgot where content was, users would have even less of an idea where to look. At this point, I clearly had a problem that I didn't have when everything was simple.
There's a point at which help files reach a threshold of findability. It doesn't happen with simple applications -- it's more a problem with semi-large help systems. And it's also more common when you have a post-release documentation methodology (in which you continue to add the help content after release).
Passing this threshold leads to a paradox that I call the information paradox: The more information you add to a help file, the more informative it becomes because it contains more information. However, as you add more information to your help file, it also becomes less informative because it's harder for users to find that information.
Here's an example. Let's say you just bought a new smart phone. In a weird hypothetical scenario, the store clerk gives you two options for help: you can either have a 5 page quick reference guide, or you can have a 500 page reference manual. But you cannot have both. Which do you choose?
If you choose the quick reference guide, you'll be able to easily read the information and understand the core tasks, but your advanced questions and tough scenarios might not be addressed. If you take the 500 page manual, it will probably address all your questions, but the process of finding the answers may be too burdensome and tedious to be worth the effort.
The information paradox comes into play here. The more information you add to a help file (in this case, the reference manual), the more informative it becomes because it contains more information. However, the reverse is simultaneously true: the more information you add to a help file, the less informative it becomes, because users can't find the information. It gets buried among the hundreds of pages.
Here's an analogy that expresses the same paradox. Let's say you have a friend who talks your ear off. The more the person talks, the more information is available; with more information, the more potentially informative the conversation is. However, the more a person talks (and yaks on and on and on, talking your ear off), he actually communicates less information, because you start tuning him out. Each new word (or paragraph and topic in a help file) gets diluted in a sea of information until you arrive at the conclusion that he "talked about everything and nothing."
Let's come back to the help situation. My assumption is that there's a point at which help topics start to break down under a mass of information. When help reaches this threshold, going beyond it actually becomes detrimental to the user because the information starts to lack continuity and focus. It gets sidelined by a myriad of notes, tips, gotchas, quirks, exceptions, side notes, references, extended explanations, details, notices, and other information. A simple process sinks under the albatross of TMI (too much information).
The activity that often pushes help over the edge is the effort to document everything. When I played a support role and tried to answer every user question by pointing users to a link in the help that answered their questions (even if I had to write it before responding), I had an idea of documenting everything. I envisioned a day when I would have a sort of omniscient manual.
But documenting everything is a controversial strategy in technical communication. Some point it out as a myth. Alistair Christie and Graham Campbell had an extended exchange on this topic in one of their podcasts. Let's suppose they're right. If you abandon the desire to document everything, and instead only focus on main questions from users, looking at the trends of questions only, do you still run into the information paradox?
If you stay behind that threshold where help still remains relatively findable, are you better off in the long run, and does the whole problem of findability go away? This is a key assumption that begins my discussion on organizing content, because if you don't document everything, if you only document selectively, chances are your users won't bang their heads in frustration looking for buried answers. You won't need to implement advanced techniques for organizing content, and your topic-based folders may not pose any issues with findability.
This isn't merely a theoretical speculation. I am seriously considering that my strategy for comprehensive documentation is flawed. A couple of years ago, I used to carpool to work with a quality engineer named Kevin. During this time, I operated under the idea that my online help would be a comprehensive source of information for the application I was documenting. It would be the omniscient manual that I was striving for, answering every user's question. But in our organization, technical writers are scarce resources. Four technical writers try to serve the needs of an 800-person IT department.
In my conversations with Kevin, many times I expressed frustrations with the lack of user assistance on projects in our organization. On many projects, project managers either omitted help or wrote it themselves. Kevin pointed out that if I really felt this way, I should begin a crusade of quick reference guides for as many applications as I could lay my hands on. The information I produce would be short, just a couple of pages, but my reach would be widespread. Not only could I provide the missing user assistance needed for so many applications, he said, with this approach I would also provide users with a form of documentation they would actually read. Like many people, Kevin believed long manuals were unread dinosaur relics that no one used or wanted. My time would be better spent keeping documentation short and sweet. Lots of quick reference guides, lots of projects, lots of influence.
I never followed Kevin's advice because I couldn't bring myself to work on a project where my deliverable was only a superficial two-pager with brief information. I couldn't forego addressing what I felt were the true needs in a help file -- those difficult questions that surface from power users and edge-case scenarios. After all, this was my own frustration as a software user: the instructions never seemed to have the answers I needed. But looking back, maybe I should have listened to Kevin.
[caption id="attachment_8481" align="alignright" width="249"] The 80-20 Rule: 80 percent of the results come from 20 percent of the efforts.
Kevin's advice follows a rule know as the 80-20 rule, or the Pareto principle. The idea is that "80 percent of the effects come from 20 percent of the causes." Let's say that it takes me 20 percent of my time to create a quick reference guide for an application. Despite only expending 1/5 of my time, the quick reference guide's effect might influence 80 percent of the users.
This sounds improportional at first, but if you think about it, the idea has merit. Imagine a scenario where you hand out both a quick reference guide and a reference manual to 100 people in a crowd. Assume everyone reads something. About 80 of them would read the quick reference guide , and only 20 would read the reference manual. Right?
Are we technical writers so ethically obtuse that we can't triage a documentation situation? We end up so bent on writing the all-encompassing reference manual, expending a lot of effort (80 percent of our effort) chasing down answers to arcane questions and edge cases that almost no one needs. Our time would be better spent focusing on the core ideas/tasks and then moving on, leaving the straggling few oddball users to make do without (you know, those users who ask for the full printed manual or who ask about running the app remotely on Ubuntu through a proxy.) Sacrifice a few for the good of the whole. This isn't murder we're talking about -- just the unfortunate circumstances of time and information. Our influence could be enormous, if we followed logic.
The result of not documenting everything invariably leads to less information. With less information, the help file is smaller and topics are more findable. A quick reference guide that is between 2 and 20 pages in length does not have a findability problem, and the whole information paradox becomes somewhat of a moot point.
In a world of 4 technical writers for 800 IT professionals, the 80-20 rule makes sense. But I also admit that it isn't ideal. In an ideal world, information is complete; all users' needs are addressed. Ultimately we continue on with the old model believing that some day, when project managers see our omniscient help systems, which reduce customer support, improve the user experience, and help user productivity soar, they'll recognize our value and hire more technical writers to document their application. That scenario, however, seems like a day on the horizon that never fully dawns. Maybe we should change our perspective.