Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]
May 17th, 2010 | Posted in blog 25 Comments »
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?
Sponsors
Tags: content, flow, linear, logic, non-linear, organization, PDF, single sourcing, structure, table of contents, Technical Writing
If you liked this post, keep updated with new content: Subscribe to I'd Rather Be Writing.
Both comments and pings are currently closed.
Mark Baker (5)
DiSc (3)
Ellis Pratt (3)
Jen (3)
Neal (3)
Richard Hamilton (3)
Jenny (2)
Sarah Maddox (2)
Sarah O'Keefe (2)
Stefan Kleineiken... (2)
This post reminds me of Mike Albers’ excellent article from 2000, “The Technical Editor and Document Databases: What the Future May Hold” (http://tc.eserver.org/13835.html). He argues that though the job of technical editor appears to be waning, it’s critically important to have someone who manages the entire document assembled from content management databases for organization, consistency, flow, and duplication. This case study, fictional though it may be, supports his point nicely.
Geoff, I wish I had access to some of the resources that I think you have access to. I tried that link but I don’t subscribe to that journal. Your tc.eserver.org library is a treasure of helpful resources, though. Thanks for the reference.
Yessss. Old-fashioned organization has been too often chucked out the window as we’ve sped into the world of topic-based writing. Great topic, Tom.
I hope to take this essay beyond old-fashioned notions of organization into more innovative organization models. Just be patient.
Nice post, Tom.
Organizing content is the most difficult part of the job when an application has different possibilities, which is the case of the software the company I work on produces.
Hope this series can help us all find solutions for this problem.
Here’s the glib, too-easy answer: At the inception of the project, there was audience analysis and there were use cases. But no one asked how the various users would actually choose to access the content.
Yet even if someone had asked, the problems you describe would’ve cropped up. No one is prescient enough to anticipate all of the user scenarios, let alone all of the ways content can get mixed up, that far in advance. Does that mean we need a shorter product cycle? But that would suggest a more topic-based approach, which (as Marcia has pointed out) is part of the problem here.
I can’t wait for your next installment. And thanks, by the way, for perking up my afternoon with a rather pleasant earworm: “Secret Agent Man” by Johnny Rivers.
Larry, good point about asking how users would actually access the content. That’s a fundamental consideration that I overlooked in the initial setup.
To be clear, I’m all for a topic-based approach. It’s just that the organization of those topics is important too. There’s not enough written about this subject — the importance of topics hanging together well. It’s hard to achieve coherence throughout a topic set, and even harder to measure it.
Tom, with absolute respect for your efforts and opinions on this topic (Tom is both a friend and colleague), I have to disagree with where you are taking us.
I think most of us would agree that when users go to the help or the manual, they’re looking for an answer to a specific problem. They want to know how to get out of an error box, or how to create a new agent account, or to understand the limitations of various user roles. Unless you’re suggesting a hybrid model–User Guide meets Training Guide–users aren’t looking for a lesson; they’re looking for a quick answer so that they can get back to being productive and avoid looking stupid. (If you disagree with this, then you can stop reading here.)
And yet what I think you are saying here seems counter-intuitive to your suggested method for achieving that goal:
Your statement makes me think that smooth transitions between topics and an overarching “story” is the key to better content organization and better documentation. Yet what you describe seems far more applicable to a fictional novel than to technical documentation. Should a manual read like a novel, with smooth transitions and a cohesive, overarching plot line? Would such an organization make it easier for a reader to find THE answer? And if so, you seem to be suggesting that the table of contents or the very order of the content could be done so efficiently as to render indexes unnecessary?
But I don’t think a manual is a novel; and I don’t know too many people who read product manuals cover-to-cover as they do a novel. Rather, like the help system, they are looking for quick explanations of concepts, instructions, or reference; and more importantly, THE answer to whatever is currently vexing them.
I confess that few things would bring tears to my eyes more than to have someone curl up before a warm fire and read my manual cover to cover, and then to call in to whatever Talk Show I might be on to tell me on the air what an amazingly moving writer I have made of myself (<: (Getting chills, even now! But alas, I’ve never been on a talk show, nor really ever expect to be!)
I think that you’re looking for shorter prose and perhaps more elegant transitions (e.g. your “200 Post-It notes” comment). At the same time, I think you're asking for reduced word-count. In contrast to your view of single-sourcing, I think that the solution is actually in thinking much more like the single-sourcing writer, really a rare skill among many technical writers today.
(ASIDE: Given the abuse of the term “single-source”, I must state here that by it I mean re-using content where ever possible as both a matter of survival for the Modern Technical Writer [soon to be a book by yours truly—a shameless plug at your expense] <: and as a method for reducing content bloat, as much as the usability of the product allows.)
The very best practice I've seen in the realm of technical communication involved a careful content analysis that generated a careful content model, which in turn facilitated the most complete and yet terse content a user could hope for. That is, when it came down to real-world application, the user found THE answer in significantly less time than when using the warm-and-fuzzy doc set belonging to the previous release of the same product.
I believe that content flow WITHIN a single topic–from idea to idea–makes for good writing and communication. But trying to write software (or hardware) into some kind of moving and holistically cohesive story is something you should reserve for your next fictional novel. Try to apply such a holistic approach to a user’s guide and this is what you’ll end up with:
- Significant bloating; your word count will sky rocket (and Tom, please don’t cite the CUBS project, as 98% of the content was written by non-writers who did not understand the content model, much less how to write terse technical content)
- Your readers won't notice much of a difference, except increased frustration by the new dilution (warm-and-fuzzy transitions)
- You’ll spend a great deal more time writing content as you work and rework "the flow" and transitions (Hemmingway style?); be prepared to negotiate more time on the schedule, unless you have the luxury of a plethora of highly skilled tech comm resources (or a very small project)
Users want only one thing: THE answer. Most of us are writers and so naturally we love to write. And whether or not we writers are willing to admit it, we hope (secretly) that someone will appreciate our personal flare and style.
BUT, this is technical writing! It’s giving users the quickest answer to their most current vexation. I’m not saying that we can’t make our writing more interesting, or that one writer’s style does not more clearly communicate ideas than another’s. But those are more issues of grammar, clarity, and style than of “content organization”. If you want to produce shorter, more consistent content, begin by identifying a content model that clearly maps to information types found in the product being documented, while at the same time shouting foul to IxD and engineering when you encounter particularly frightening usability issues in the product (as early in the dev cycle as you are allowed).
One parting shot (before I duck)…I have met one or two people from the apparently 1 percentile who prefer to read the manual cover to cover. But it makes no sense (nor can we afford) to write for them while the other 99% are saying, "Look, I just want to know how to reassign role X to user Y." The catch is anticipating the million-and-one questions users will be asking, and that begins with user and content analysis and the building of an intelligent content model designed to reduce word-count while maximizing the probability of covering the majority of user questions and concerns. (Okay, ducking!)
Derek, thanks for the detailed and passionate response. I partly agree with you. Here’s what I’m thinking right now. Because print provides a more linear reading experience, the TOC for print must be substantially different from the TOC for webhelp. When I initially created my documentation, I straightway single-sourced it from webhelp to a printed manual, more or less. As I read through the PDF, I lost all patience after page 50, and I found the whole experience jarring and mish-mashed together.
If people hope to print out a manual, we should craft a linear, semi-seamless reading experience for them. This may mean drastically reducing the page count (from 197 to about 65 pages). It will mean eliminating all the advanced or fringe case topics. And it will mean providing some sense of coherence within the chapters. Not necessarily a novelistic coherence, where transitions flow with story-like cohesion. But basically the chapter should begin with an About topic, perhaps, and then provide several of the core how-to topics for that chapter.
I don’t think many people print out a manual and use it in the same way they do online help. With online help, people search for a quick answer to a problem. But when someone prints out a manual, they’re aiming for conceptual understanding of a product. Hence the printed PDF should be more conceptual-based and have more flow. We have to organize the content for the medium, essentially.
EPILOGUE
Let the length of my previous reply suggest that the clarion call for Twittering and briefer blogs are yet additional symptoms of the rising Distracted Generation, which almost uniformly displays an innate inability to focus for greater than half a page of content, per sitting. I’m all for brevity, but our language does dictate the rate at which we are able to communicate. (<:
The need for brevity in online content is one of the reasons why I’m serializing this essay. But again, you make a good point about fitting organization not just to the content, but to the medium.
Derek is right that users just want THE answer. Part of what Tom’s saying, I think, is that poor organization gets in the way of exactly this goal.
The problem is most noticable in print. But even online, coherence — and therefore findability and usability — suffer when overall organization is lacking. A search function doesn’t eliminate the need for a good organizational scheme.
I don’t hear Tom advocating a return to cover-to-cover linear writing that abandons all that we’ve learned about topic-based writing. What he’s acknowledging is that for maximum usability, topics need to work not only individually but also as a set.
Ignoring for the moment the differences between online and print media, Tom points to the need for smart groupings and well-thought-out relationships between the topics.
As a side benefit, I suspect that the more attention we pay to these architectural elements, the more opportunities we’ll find to improve the content in the individual topics as we go.
The best online Help I’ve have the good fortune to use has worked well both at the granular (topic) level AND in sequence from one topic to another. For some time, this has seemed to me to be the frontier in research on topic-based writing.
Thanks for your thoughts, Marcia. You could be right about Tom’s intentions; I look forward to hearing his thoughts. And if you’re correct in your assumptions about his meaning, then I think we’re saying the same thing regarding the value of structure. Because I’m also not abdicating abandonment of, say grouping like features within cohesive chapters.
But writing a topic so that it can both stand alone and appear within a broader context (e.g. help and print) without loss of meaning also means that the “smooth transition” we’ve come to love in the metaphor of the book is a small sacrifice to pay for the gained benefits (which to me are the ability to deliver more with less effort while still delivering THE answer to the user).
Cheers!
Marcia, . I agree that “smart groupings and well-thought-out relationships between the topics” can’t be ignored, even in webhelp. However, the direction I’m moving towards right now is toward a faceted navigation TOC model. No single TOC hierarchy can come across as logical for every user. But that’s okay, because online mediums allow you to transcend the limitations of traditional print organizations. You can take the same content and look at it from 15 different angles in a way that just isn’t possible in print.
By the way, I love the conversation that is taking place in the comments.
In your case study a couple of things jump out that I would really care about during an actual project. In your description you didn’t use the term ‘user goals’ nor the word ‘model’.
Put generically, a technology product exists to support the user’s accomplishing some set of real-world goals. The user reaches those goals by performing some set of tasks that involve ‘using’ the product or being assisted by the product.
Describing how to perform each task *procedurally* is a key purpose of the assistance documents (including the product’s online help). But a second key purpose is to describe *conceptually* the product’s built-in assumptions about the user’s goals and how the product-assisted tasks contribute to achieving them.
For a given technology product, the correspondence (or ‘mapping’) between tasks and goals might be loosely or tightly defined, depending on the subject matter involved and the degree of formality (or informational rigor) required to progress toward the various goals.
As for your case study, a technology product that supports achieving a non-trivial number of user goals (such as 10 or more) might provide *dozens* of product-assisted tasks. If distinct goals have built-in dependencies, such as user identity or privilege, there can multiple possible paths among the tasks, so it will be important for the writer to identify, and signify, the distinguishing features of each given path among the required tasks. This has to do with the ‘dimensionality’ of the task-paths: how the user understands differences among task-paths, how the product presents them, how to choose and navigate a given task-path, and so on.
In my experience, it helps for the writer to have some understanding (that is, after interviewing the product’s designers) of the ‘model’ that the product uses to internally represent both the user goals and how the product-assisted tasks contribute to achieving them. For example: Are goals inherently distinct from each other, or are there attributes of any two goals that are the same? Which tasks are ‘necessary’ in relation to each other? In what ways does the product keep track of the user’s progress toward the user goals? Of course, the more complex the product, the more the writer is dependent upon the product designers to have thought through these various issues.
For this case study, the identity or privilege level of a given user is inherently a variable, whereas the ‘target objects’ (that is, the lists, reports, etc.) of the product-assisted tasks are the constants. Thus I suggest that the assistance documents be explicitly organized around the product’s targets; that is, the tasks are ‘children’ of the targets, but filtered by privilege level. Each task topic should also include a link to (1) the conceptual topic that describes that task’s target and (2) the conceptual topic that explains how that target’s task work together at a higher level.
[Aside: Because in this case study the technology product is itself a simulation tool, there is an additional level of abstraction between the user and real-world goals and tasks. In addition to describing the objects and actions that exist 'within' the simulation, the assistance documents must also describe the simulation environment's own framework and conventions. Sigh!]
Paul, I appreciate your insight here. Too often I’m guilty of severing the tasks from the conceptual topics. We often become so familiar and blind with the application that we lose sight of the conceptual underpinning that gives purpose to the task in the first place.
You wrote,
Fundamentally, it’s the combination of this task + concept that has be maintained in the printed material in order for the content to be readable to the user. In online help organizations, you can include a string of tasks that merely refer to a concept in another part of the online help with a simple link. In online help, it’s just a click away. But I think in printed documents, separating tasks from concepts with too many pages in between makes document lose appeal and coherence.
Tom, you wrote,
“In online help organizations, you can include a string of tasks that merely refer to a concept in another part of the online help with a simple link. In online help, it’s just a click away. But I think in printed documents, separating tasks from concepts with too many pages in between makes document lose appeal and coherence.”
This is a helpful insight into the difference between the user experience of online Help vs. the print (or PDF) version of that same topic set.
It’s tricky, of course, anticipating the order in which people will want to read topics in print. Even when the topics are arranged in the most logical progression possible for cover-to-cover readers, other readers will jump around to skip what they don’t need — and “what they don’t need” will be different for each reader.
Ideally, we’d build a logical page-to-page progression (paying attention to the proximity and order of concepts and tasks, for example), AND provide “related topics” cross-references in print, just as in online Help.
That’s one of my pet peeves with the CMS that my team has just started using (one of the big name CMSs, for what it’s worth). By default, the “related topics” from our reltable show up beautifully in online Help, but we can’t get them in our PDFs without, I presume, getting an XSLT expert in.
At the bottom of each “task” topic, include explicit pointers to each “concept” topic that the task relies upon. Not a big deal even in a printed manual, right? I’ve delivered this kind of document design myself.
Yes, including explicit pointers to the concept topics is the ideal. I’ve done this before for print docs in FrameMaker using cross-references.
In our new CMS, though, where topics are mixed and matched differently for various outputs, we can’t build those pointers into the topic files, since the topics available to point TO will vary with the output map. So, for each output map we create a relationship table, which stands outside of the topics and which puts those pointers at the end of each topic beautifully… in the online Help.
Only in the online Help.
I don’t know why but, by default, the relationship tables can’t provide the same helpful function when we output the same topic set to a PDF. Theoretically, it’s possible. I wish the system had been designed to support this functionality “out of the box.” For now, we’re stuck. No one on my team has the skills to customize our CMS outputs in this way.
I didn’t know relationship table links didn’t output to PDF. I used relationship tables for a set of related links for each topic in my online help, but I just finished stripping all of them out. They didn’t quite work the same way as tags, and it’s easier to maintain a concept marker than a relationship table. Also, the links in the relationship table were being counted in the search engine results, which isn’t something I wanted to happen.
I’m hoping that relationship table links can be made to output to PDF. I think it’s just that our particular system, by default, excludes them from PDFs. Interesting to hear that you’ve abandoned your rel table links.
@Derek:
Your comments prompt me to reflect back to you the notion of who TWs are writing for. Compare it to the features found in a mass-market American automobile. What should the automobile maker assume is the level of training/awareness/intelligence/dexterity/vision/eye-hand coordination/etc required to operate that automobile in a safe, and lawful manner?
Similarly, should TWs be writing assistance documents for the XX% of technology product users who (1) haven’t taken formal training in using the product, (2) aren’t educated/trained to competently perform the real-world tasks that the product was designed to address, (3) refuse to read the packaged documentation under any circumstances (that is, are textually challenged), (4) have American English as a second/third/etc language, (5) suffer from ADHD or ADD, (6) are burdened by their supervisors/employers with unreasonable demands on their time and productivity while operating the product, etc.?
Shouldn’t TWs be allowed to recommend a more reasonable and complete list of knowledge prerequisites for their audiences? What prevents this from happening at our jobs?
My point here is to question the notion of the “heroic” technical writer, the person tasked with clairvoyantly anticipating every possible user question about any possible incorrect usage of a technology product, even one that is insufficiently designed and whose audience is incompletely identified.
That is a great point, Paul. It is frustrating to me to be called in to document a product when the user interface is already finished (no chance of fixing usability issues) and when the team leads believe that the documentation will “automagically” solve user confusion…documentation as a band-aid. And yet, this is such a common scenario.