Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]

by Tom Johnson on May 17, 2010
categories: findability • technical-writing

Let's fast forward a year. Assume you have explored Swordfish and have hammered out a lot of help topics -- nearly 200 help topics, in fact. You have met with subject matter experts and extracted critical information from them for many months. You have explored Swordfish inside and out, documenting every possible task and setting, and now you have a ton of content.

The help topics you created seem endless. You have checked their accuracy against the constantly updated Swordfish interface, and you have made a seamless flow from online help to PDF format. But now, at this moment, near the end of the project, you face the problem of content organization. You have so much content, it seems all one giant jumble of information. It needs to be organized better, with a sounder logic and structure, but how?

Attempting organization

In setting up my 200 help topics, I initially grouped the topics  into various folders -- for example, Covert Operations, Stings, Exchanges, Drop-offs. And then I titled the subfolders in each folder as "Basic Tasks" and "Advanced Tasks" to follow the model of increasing agent permissions. So the folder organization looked like this:

Covert Operations
     Basic Tasks
     Advanced Tasks

Stings
     Basic Tasks
     Advanced Tasks

Exchanges
     Basic Tasks
     Advanced Tasks

Drop-offs
     Basic Tasks
     Advanced Tasks

It soon was clear that no one understood what constituted a basic and advanced task, so I changed these subfolders to a grouping of content by role: "Super Agent Tasks" and "Regular Agent Tasks." I structured everything in the help this way, assuming that this model would fit the majority of agents perusing the help. They could then navigate to the subfolders based on their known and probable role.

Covert Operations
     Regular Agent Tasks
     Super Agent Tasks

Stings
     Regular Agent Tasks
     Super Agent Tasks

Exchanges
     Regular Agent Tasks
     Super Agent Tasks

Drop-offs
     Regular Agent Tasks
     Super Agent Tasks

Feedback from both colleagues and users resisted these roles. "The folders are too general," one colleague said. "I have no idea what Regular Agent and Super Agent Tasks mean. You need something more descriptive." A user echoed the same thing, asserting that the folders were too general and vague.

Technical distractions

Release dates drew near. Although the folder naming conventions weren't ideal, I was proud of the single sourcing model I had set up. The online help single sourced to a PDF printout without any modification of the PDF at all. In fact, I even set up a recurring job to automatically republish both the online help and PDF every day at 2 p.m. It was a completely hands-off, automated process.

But then something happened. A few days ago, one of the chief agents in the department mentioned he was preparing a presentation to a set of field agents, and could I show him where to print the quick reference guides and user manuals?

Gladly I showed him the links, but because I had a few days until the deadline, I decided first to read through the PDF, which previously I had hardly glanced at except to ensure proper formatting and PDF rendering.

Printing out the PDF, which essentially duplicated the online help but in print format, was 197 pages. I didn't realize it was so long, but I pulled out my red pen and started to proceed through the topics with patience and anticipation.

Non-linearity and linearity

As I moved from topic to topic, I noticed that the topics didn't flow well together. Some topics repeated information stated on other topics. Other topics introduced concepts in some places but didn't include tasks related to those concepts until pages later, as they were interrupted by other topics.

Overall the content was too detailed, too wordy, and too long. I drew big red slashes on numerous pages and wrote "Cut" more times than I could count. I wanted a shorter reading experience. After page 50, I had read all I wanted to.

The chief agent's assistant also agreed that she could not print 197 pages for each participant. The length seemed ridiculous. Was the application really that complicated?

Somewhere, something had gone wrong. I entered into the project with a couple of assumptions. First, I assumed help should be a mile wide and thirty seconds deep, that is, covering a wide array of topics in a brief way. Consequently, I had written dozens and dozens of topics that covered all kinds of scenarios. This might have been all right had I left the miles of topics in the online help, but I had also included these topics in the PDF.

Reading through the PDF, there was no flow, no tight coherence of ideas, no transitions from one idea and topic to the next. It was if someone gathered 200 Post-it notes written independently of each other and positioned them sequentially -- and then was surprised when the content lacked flow from one Post-it note to the next.

I had another faulty assumption, one that I knew but had forgotten. Online help is a non-linear reading experience. A printed document is a linear reading experience. The two reading modes aren't interchangeable. Reading through the PDF made that clear.

Crumbling organization

I noticed another problem in reading the PDF. The chapter titles Super Agent Tasks and Agent Tasks began to annoy me, even more now than before. What did they really mean? Nothing. As my colleague had pointed out, the titles only meant something if you knew what sort of tasks each role could perform (which I did).

But if you didn't already know the limits of each role, grouping topics by role wasn't helpful. You would only know to look in that role's folder if you knew that role could perform that task. But most users wouldn't know the tasks each role could perform. Many of them wouldn't even know what roles the application had. So the folder names were somewhat meaningless.

The help file was falling apart on two levels now: poor folder/chapter titles, which left the organization of tasks vague. And also a hodgepodge of clashing topics in the PDF output, which didn't result in a linear reading experience.

More content, but no space for it

Unfortunately, that's not the whole of it. As you may have guessed, I also created an abundance of video tutorials for Swordfish. Agents who viewed my videos in the past always gave me positive feedback about the videos, so I created 30 short videos for Swordfish -- with transcripts -- that I included in the help.

But the scripts for the videos didn't quite match the help topics on a 1:1 basis. Videos needed an infusion of conceptual information and tasks, sometimes several tasks and concepts in the same video. And videos needed more of a conversational voice. The model of one help topic per video didn't work.

My videos and their related scripts were a combination of both concepts and tasks, sometimes spanning several topics. This made it hard to place videos in the right places in the help, because they didn't always fit the topic or folder I would embed them into. Consequently, I made videos their own topics.

To organize the videos in the help, I created subfolders called Videos that would be next to the Super Agent Tasks and Regular Agent Tasks folders. Now my help structure looked like this:

Covert Operations
     Videos
     Regular Agent Tasks
     Super Agent Tasks

Stings
     Videos
     Regular Agent Tasks
     Super Agent Tasks

Exchanges
     Videos
     Regular Agent Tasks
     Super Agent Tasks

Drop-offs
     Videos
     Regular Agent Tasks
     Super Agent Tasks
Where do the CSH topics go?

I also had one more set of topics: Screens. Since I had made the help context-sensitive, I had a specific topic for every screen. I named these context-sensitive topics after the screens they appeared on, so that if you looked at the Black Ops Team tab, the context-sensitive help was named Black Ops Team tab. These topics I included in their own subfolder called Screens. So now my organization looked like this:

Covert Operations
     Videos
     Screens
     Regular Agent Tasks
     Super Agent Tasks

Stings
     Videos
     Screens
     Regular Agent Tasks
     Super Agent Tasks

Exchanges
     Videos
     Screens
     Regular Agent Tasks
     Super Agent Tasks

Drop-offs
     Videos
     Screens
     Regular Agent Tasks
     Super Agent Tasks

Reading through the PDFs, looking at my topic organization, and trying to fit the video content and screens in the help, I realized the organization of my help content failed. I had become so bent on single sourcing, on integrating relationship tables, on inserting videos using javascript and custom-sized pop-up windows, on implementing mini-table of contents, on adding CSS background images for my notes and tips, and on coordinating the context-sensitive help that I neglected one of the most important aspects of the help: content organization.

A Yeats poem came to mind:

Turning and turning in the widening gyre
The falcon cannot hear the falconer;
Things fall apart; the centre cannot hold;
Mere anarchy is loosed upon the world,

I didn't have much time before my deadline to deliver the printed PDFs to the chief super agent. I realized that he probably wouldn't read the help closely, but perhaps his audience would. Would they see the same incoherence I saw? Many of the topics were good, but they didn't fit together in a logical, readable way. I feared the super agent would see this mishmash of content and cast doubt on the help content as a whole. How could I organize this content in a better way?

Next: 1.4 Imposing Order Versus Observing Order [Organizing Content 4]