We worry far too much about trying to create a logical well organized documentation set. We would do well to focus more on writing one good page.
It used to be that music lovers would have to buy a whole album just to get the one or two songs that they really wanted. Today, you can buy just the tracks you want and assemble your own playlists combining songs from any artist in any order you want.
We used to buy collections; now we buy individual items and create our own collections.
It wasn’t that long ago when we were forced to buy cable packages that grouped a number of channels into one package. Sometimes we bought the package because we wanted to watch one show on one of those channels. Today, people are flocking to services like Netflix , Hulu or Roku that let them watch just the shows they want.
The personalized aggregation trend is impacting the newspaper and magazine business, as we increasingly get our news from personalized aggregation apps like Flipboard. Eddie Vassallo reports that the tablet magazine, launched with great fanfare such a short time ago, is sinking fast:
It’s also no secret that tablet magazines are simply not being read – the form factor and technology is basically making the standardized magazine page a near anachronism in a world of dynamic live canvases of the caliber of a Flipboard or Zite.
And yes, the same thing is happening in the world of technical communication. People’s first resort, when they have a problem, is to ask a friend or an expert, something they increasingly do online rather than in person. (The average time it takes to get an answer to a software development question on StackOverflow is 11 minutes.) If asking fails, their second choice, more and more frequently, is not to open a manual, but to Google it.
The documentation set is irrelevant to your users
People are not looking for orderly collections of technical content. They are looking for the one topic that answers their immediate question, and they don’t particularly care which collection it belongs to, or if it belongs to any collection at all.
Ask yourself this: the last time you found an answer to a technical question on line, how big was the documentation set it came from? Most of the time you will have no idea. And why would you? Knowing the size of a collection is irrelevant once you have found the thing you are looking for. How big is Amazon? How big is Wikipedia? How big is Stack Overflow? We don’t know. We don’t need to know. It would probably scare the bejeebers out of us if we did know.
Space is big. You just won’t believe how vastly, hugely, mind-bogglingly big it is. I mean, you may think it’s a long way down the road to the chemist’s, but that’s just peanuts to space.
Douglas Adams, The Hitchhiker’s Guide to the Galaxy
A recent discussion with Tom Johnson prompts the thought that we spend too much time worrying about the documentation set, and not enough about its individual pages. Our readers very rarely look at the documentation set as a whole. They look at individual pages to solve individual problems. (This is not news. We’ve known this for a very long time.)Tom and I were discussing the role of reuse and the TOC in online documentation. Tom pointed out that the use of the tri-pane help paradigm forces you to repeat content in multiple places, rather than simply publishing it once and linking to it as required, and noted the lack of examples of online tech comm that follow something other than the tri-pane model (with a TOC shown on every page). He suggested the WordPress Codex as one example, but commented:
I wouldn’t hold up the WP Codex as a model to follow. Their documentation is pretty scattered, fragmented, hard to follow, frequently out of date, and confusingly organized.
Since I have found a lot of useful information in the WordPress Codex, I was a little surprised by this statement. I checked it out, and sure enough, if you look at the Codex as a whole, it shows all of these faults. This was plain enough to see when I looked at it with the eye of a technical writer.
But I have been using WordPress for nearly three years, and I have had to solve a number of problems and get information on how to do things I wanted to do with it, and never in all that time had I noticed these defects of the WordPress Codex.
Why not? The reason, I am convinced, is that when I have a problem or a question with WordPress, I Google for an answer. Google has led me to some really good pages in the WordPress Codex. I even use one as an example in my book (Every Page is Page One: Topic-based Writing for Technical Communication and the Web).
Online findability doesn’t depend on a TOC
Are there really bad pages in the Codex as well? Yes, as it turns out. But I never see them when I search for help on WordPress, presumably because Google knows what the most popular pages are on those topics that the Codex treats badly, and they are all on other sites or forums. I don’t see the bad Codex pages because Google finds me good pages on other sites.
Do I find good answers to my WordPress questions? Yes, almost always. Do they all come from the Codex? No. Do I care? No. As long as I get an answer to my question, I don’t much care (or even much notice) where it comes from.
Is the Codex hard to navigate? I don’t know, because I’ve never tried. Never once did I go to the Codex and try to navigate its structure. I Googled for the information I needed, and sometimes Google found pages in the Codex. I navigated the Web, not the Codex.
Certainly, the good Codex articles I found contained good links to other good content, some of it in the Codex and some of it elsewhere. So those good pages also had good navigation, and I used it. But that was the navigation of the individual pages, not the navigation of the Codex.
Would putting a TOC on the Codex improve the poor content? I doubt it. Would it make it easier to find things in the Codex? I doubt that too, because I would still Google for answers to my WordPress questions.
What I fear, though, is that if the Codex was to be made over into a tri-pane help system that the quality of the individual good articles in it might actually go down, and particularly that their good navigation links (which often lead outside the Codex) would be lost.
Why do I fear this? Because when you start with a TOC (and most doc plans do), you bring your focus out to the whole. Complete coverage becomes the overriding goal, and the standard for individual pieces becomes, implicitly at least, “do they cover their assigned area?” But coverage is not excellence, and neither is ease of navigation.
What the user cares about, on every occasion in which they look for help, is neither the coverage of a particular information set, nor even its ease of navigation. They care about the quality of the individual topic they are reading. A comprehensive documentation set with great navigation and second-rate content is not going to satisfy any user’s needs.
In a world where it is so easy to find both content and experienced people to fill in the gaps for you, and in which search algorithms and social curation tirelessly sift out the dross and bring the best content forward, the real key to serving user’s needs (and in keeping their eyeballs on your content and on your site) lies in an individual piece of content that meet their needs and meet them well— one good page.
No one wants to discover the documentation
Another common argument for the TOC is that it allows the reader to discover the rest of the documentation set, which they might otherwise not encounter if they just focused on one page and the pages it links to. The problem with this argument is that the user is generally not interested in discovering the rest of the documentation set. Nor are they thirsting for more of your deathless prose (sorry!). They are trying to solve a problem and get back to work, and the only content they are interested in is the content that addresses their current problem. The only content they want to read apart from the current topic are closely related pages that address ancillary issues of immediate interest to them. That is what links are for.
Write one good page, and link it to other pages with related information and you will have created all the information set that the current user wants and needs to address their current problem. That is the best thing you can possibly do for your readers today.
Don’t misunderstand me here. I am not arguing for randomness, or for unplanned documentation sets. I believe strongly in structured information sets, in structured topics, and in a disciplined approach to technical communication. But I don’t believe that any of these things require a top down approach, or that any of them require a TOC, now we are in the age of the search engine.
The myth of comprehensive documentation
The idea of a comprehensive documentation set is a snare and a delusion. Fix this in your mind before you begin: you will never create a comprehensive documentation set. A good documentation set should support users’ tasks. Unless your product is so trivial that it hardly requires documentation at all, the tasks that people attempt with it, and (equally importantly) the background and expectations they bring to those tasks, multiply indefinitely. Comprehensive can only be defined in trivial terms, such as “a topic for every menu item” or “and article on every feature.” Indeed, the quest to be comprehensive leads teams into creating feature-centric documentation, since being feature-centric is the only way to get a metric against which to measure how comprehensive your content is.
Even if you can define comprehensive in non-trivial terms for your content set, do you really have the time to do full justice to every feature and task? Most organizations are too resource constrained to keep up, and most have a backlog of defects which put them further behind. In such an environment, making comprehensive the first priority is a sure recipe for creating a trivial, mediocre documentation set that solves no one’s real world problems. In such an environment, writers have no time to create ANY good pages, and the resulting documentation is comprehensive in feature coverage but entirely vacuous in meeting user’s needs.
What’s worse is that as long as you keep trying to be comprehensive, it will never get better. You will spend all your time keeping your meagre but comprehensive coverage up to date, without ever creating a single really good page.
How do you dig out of this hole? Write one good page. Tomorrow, write another good page, and the next day and the next. Make it your first priority to make sure that every page you do create is a good page that delivers real value to the reader. Your coverage may not be comprehensive, but at least your documentation will be useful for some needs.
And if it is useful for some needs, it may actually end up being read by some people. And that is about as good as it gets in the real world.
Write one good page.
