Our system of organization partly determines the findability of the content. Without findability, we might as well not even write help at all. It’s exactly this lack of organization/findability that turns so many users off with help content. When you click the help button and see an immense amount of folders and subfolders and sub-subfolders, all organized in seemingly impenetrable ways, it overwhelms users. They give up within seconds of their foray into the help.

As help authors, it’s so easy to be seduced by technical distractions and overlook the content. We get drawn into styles and design, the look and feel of the help content, the single source rendering between print and online, the parallelism of titles, and the exacting conformity to our style guide. These technical bells and whistles distract us from more fundamental matters of content organization.

But content organization is fascinating. The way a help author lays out the help topics in a table of contents shows you more than simply a list of topics. It shows you how the author has wrapped his or her mind around the content, how he or she has chosen to shape order from chaos. It shows you how the author understands the user. And it shows you one perspective on the structure of the content.

Organizing the Periodic Table of Elements

Organizing a jumble of help topics into a natural, beautiful order that strikes clarity in the mind of the user is no different from the scientific urge to classify, to organize, label, and categorize. Nothing illustrates this better than the story of how Dmitri Mendeleev organized the Periodic Table of Elements.

Dmitri Mendeleev

Before Dmitri Mendeleev organized the table, he traveled extensively in Russia on trains flipping around a stack of cards that had the elements and their behaviors written on them. Sorting and resorting the cards, he kept searching over and over in his mind for a pattern, for a principle he could observe that would lend itself as the organizing pattern for the elements.

Sure, the elements had different atomic masses. The atoms of some elements were heavy; others were light. But the atoms also displayed other behaviors. Some elements were friendly with other elements; other elements were shy, like loners.

This seemingly random array of heavy, light, shy, friendly characteristics made it tricky to organize the content in a logical way. What was the right way to organize these 90+ elements? What underlying logic explained the element’s natural classification and hierarchy?

The right system of organization finally came to Mendeleev in a dream. A sudden flash of insight, not an order he created, but an order inherent in the content he observed. He finally saw the elemental grid.

He not only arranged the elements by the degree of atomic heaviness, but also found that the elements had other patterns that repeated periodically. Hence Mendeleev called his table a periodic table, because the patterns repeated with specific periodicity. Through the repetition of this pattern, Mendeleev also predicted the existence of elements not yet discovered.

Radiolab

I listened to this story of Mendeleev organizing the elements on Radiolab, with hosts Jad Abumrad and Robert Krulwich. They ended the story with the following question: Was this organization an invention that Mendeleev imposed on this otherwise random set of elements? Or did Mendeleev see the underlying law that naturally organized the elements? In other words, is organization a human fabrication we impose on content, or do we observe an organization that is naturally inherent in the content?

By the way, I excerpted a short, one-minute clip from the Radiolab podcast here. Listen to the way Oliver Sacks, Abumrad, and Krulwich tell the story of Mendeleev:

Mendeleev apparently rode these trains for years before finally reaching his organizing vision. Here Abumrad and Krulwich elaborate on the principle that Mendeleev rationalized:

And the final result today:

Periodic Table

The Problem with Scientific Classification

After listening to the story of Mendeleev organizing the elements, I was convinced I too could find, if I just looked carefully enough, an underling pattern that would serve as the perfect organization for my 200 help topics with Project Swordfish.

But the more I looked, and the harder I thought, I could not come to any conclusion except that a software application is man-made. It does not conform to any unseen natural laws in universe, and finding a natural pattern is an unachievable illusion.

The only system of organization that approximates a natural law is to organize help according to the psychology of the user. In other words, rather than looking at an underling organizational structure in the content, look at the way the user’s mind organizes and structures the content instead, and use that mental principle as the pattern.

Having thought through all of that, somewhat fruitlessly, I scrapped the other content organizations and created a standard topic-based TOC that looked somewhat like the following:

Exchanges
     Organizing Exchange Locations
     Evaluating Suitable Environments
     Reading Informant Microgestures

Burn Notices
     About Burn Notices
     Managing Your Life After the Burn Notice
     Dealing with Fake Burn Notices for Double Agents

Sting Operations
     Finding and Using Citizen Operatives
     Recycling Burned Agents for New Operations
     Evaluating Environments in High Risk Situations
     Deciphering Informant Trust
     Calculating Risks Based on Informant Credibility and Environment Security

This approach to the TOC follows the conventional topic-based approach, attempting to group like-minded content into its logical topic container.

Limits of Logic

This standard seems like a good approach, except that topics don’t always fit neatly into their “logical” containers. You can see that in the last section, Sting Operations, the tasks include evaluation of informants and assessment of environments — similar to topics under Exchanges. The remaining help topics also contained similar overlap.

The lack of a clean, neat grouping of content into topic containers is not just an exception, like the egg-laying platypus is an exception to its mammalian classification. Content in real projects is messy. It overlaps. It duplicates. It stretches outside of its row like an overgrown tangle of weeds. It could easily be classified in several different containers. When you look at the logic of the organization, it often tells you more about the organizer than the actual content. In the end, it isn’t really logical at all.

According to Abe Crystal in the Tech Comm Journal, “the idea of a single, unified hierarchy,” in other words, the standard topic-based containers organized in a hierarchical, logical arrangement, is “the fundamental weakness of standard IA [information architecture] frameworks.”

Yes, this single, unified hierarchy, the traditional topic-based approach to classifying content, which I struggled to grasp and implement with my 200 topics, is an old, tired framework. Instead, Crystal suggests moving in a more fruitful direction:  faceted classification.

—————-

Crystal, Abe. “Facets Are Fundamental: Rethinking Information Architecture Frameworks.” Technical Communication Journal, Vol 54, No 1, Feb 2007

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

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?

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Now I have a confession to make. I really didn’t want to talk about roles and hats and value. I wanted to talk about story. But I didn’t want to talk about story directly. Instead, I wanted to illustrate it by structuring my entire presentation as a story.

You’ve seen that with each of the headings, I labeled a component of the story. I began with a problem and a yearning, and moved through a series of catalysts that brought about change, ultimately leading to a crisis point that presented a crossroads, and finally an epiphany and a resolution.

Whatever role we play, our core deliverable, our most important contribution will probably still remain the written word. For the most part, we are writers. I said at the beginning that many organizations feel that “anyone can write.” When you focus only on grammar and style, on rhythm and diction, on correct punctuation and format, then ultimately it’s true: any literate person with a college degree can do a good enough job to pass off as a competent writer. But good writing is more than the text. Good writing is story. Story is the magic formula that makes everything work.

When we think of story, we often think of novels and fiction. Conflict, change, and resolution. But if you loosen up the definition of story a bit, you can see its application everywhere. When a user encounters a problem and attempts to find a solution, that’s story. Good stories also involve the element of change, but even flat stories (without much change in the characters) are still stories.

When we write blog posts, or marketing material, or give presentations, it’s easy to see how to implement story. You paint a picture of the problem that you or the user are up against, the complexities and attempts to solve the problem, and finally the resolution.

But writing documentation also follows a similar process. You get inside your users’ heads and think about the problems they’re trying to solve. Not only the problems they’re trying to solve, but the problems they’ll run into with the application as they’re trying to solve the problems. The solutions you find and present will provide the ending to the user’s story.

You have all the elements of the story in technical communication: motivation, conflict, change, and resolution. It’s not just a model for fiction writers. In fact, Whitney Quesenbery and Kevin Brooks have just written an entire book called Storytelling the User Experience. Whitney sent me an advanced copy that I’m reading now, and it’s fascinating. Early in the book, she quotes Ira Glass, host of This American Life, to explain the power of story:

Until you hear a story and you can understand that experience, you don’t know what you are talking about. There has to be a person’s story that you hear, where finally you get a picture in your head of what it would be like to be that person. Until that moment, you know nothing, and you deal with the information you are given in a flawed way.

Not only will our communication be ineffectual without story, without understanding our users’ stories, we won’t be able to know what to communicate.

Carry the story mindset with you in any situation — not just writing the documentation, but in designing the user interface, in creating test scenarios, in presenting training to users — and you will see your writing take on a whole new life and energy. You will become a better writer, for sure. But more important, when you involve story, you will also become better at whatever role you play.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Ann Rockley

A few years ago, I wanted to better understand content management, so I picked up Managing Enterprise Content, by Ann Rockley, and read it through. It opened my eyes to a lot of new concepts.

Ann is one of our field’s leading experts in content management. She’s now expanding in to something she calls “intelligent content.”

Intelligent content is a concept that builds on other concepts you may already be familiar with. I think we’re going to hear a lot more about intelligent content. In fact, she and Scott Abel are preparing an entire conference exploring intelligent content. I caught up with Ann over email and asked her to expand on the concept. Below is our interview.

What is intelligent content?

We define it this way: Intelligent content is structurally rich and semantically aware, and is therefore automatically discoverable, reusable, reconfigurable, and adaptable.

Let me explain more what that means.

Structurally rich

“Structurally rich” means the content is structured content, and more importantly it is semantically structured content. For example, we can look at the structure and know what type of content it contains (steps contain chronological action-oriented information). DITA-based content is an example of structurally rich content, as is DocBook, XBRL, and RSS, though the content could have a custom structure as well).

If we have a structure in our content, we can manipulate it. For example, we can automatically determine how to publish it to multiple channels (print, web, help, mobile), or we can filter out some content (e.g., tables may not work as well in the mobile environment).

Also, if it is structurally rich we can perform searches and narrow our search to the particular type of information we are interested in (e.g., look for all occurrences of the word metadata in conceptual information).

Semantically aware

The word semantic refers to “meaning.” Semantically aware content is content that has been tagged with metadata to identify the kind of content within it. For example, you might tag your content with industry, role or audience, and product. If the content is tagged with semantic metadata, it is possible to automatically build customized information sets based on audience or industry, for example.

As more organizations start to create personalized content (content which is dynamically assembled upon user request that specifically matches a users need or user profile), this type of metadata becomes extremely important.

In addition, as content is pushed to wikis, integrated through “mashups” or “pipes,” it becomes even more important to ensure our content is semantically tagged. Without semantic metadata, it’s difficult to automatically, let alone manually, find the content we need.

Discoverable

If the content has semantic tags and is structurally rich, it’s a whole lot easier to find exactly what we are looking for.

Reusable

Reusability refers to content we frequently use. If content is structured for reuse, and I know what type of content it is, I can either easily retrieve it for manual reuse or automatically retrieve it for systematic reuse (automatic reuse).

Reconfigurable

Knowing the structure of the content, we can output it to multiple channels, reconfiguring it to best meet the needs of the channel, or we can automatically mix and match content to provide us with the information the customers needs. We can even transform content (reconfigure it) from one structure to another, but only if we know what the structure is in the first place.

Adaptable

We frequently create our content for a particular need or audience, but content can be adapted (used in a different way), often without our knowledge, to meet a new need.

Is “intelligent content” a new term for our industry? If so, who coined it?

As far as technical communication goes, “intelligent content” is a new term. In some ways, it’s a new term in the broader content industry as well.

I coined the term, just like I did for much of the terminology used today for reuse because there wasn’t a term to describe something that existed, or there were too many terms, and talking about something or trying to explain something was difficult.

Technical communicators are very focused on producing high quality content that meets the customers’ needs, often in a very short period time and often with tools that won’t stretch to meet their needs. Many have begun to move to DITA and some are adopting content management, but when you have the conversation with management about why they should move to DITA and adopt content management, it is very difficult to get across the concepts and the return on investment. DITA is a standard, content management is a tool, but how does it help the organization to do what they need to do better?

I’ve heard some managers respond to a well-presented business case with, “So, why should I care, how does this really help us?” Let’s turn it around, let’s talk about the goal and what it gives the organization and the customer. Intelligent content allows us to do the following:

• Automatically publish to multiple channels because the content is structured. Content structure can be recognized and automatically transformed to any format we like. This is not possible with traditional content.
• Customize our content for customers because we can identify what content is appropriate for what customer.
• Reduce the costs of translation because content is modular and designed for reuse, etc.

Why is it intelligent? Because it is structured, etc.

How do we support intelligent content? With DITA, component content management, etc.

Now let’s take the concept of Intelligent Content outside of Technical Communication. There are huge amounts of information in organizations being provided on websites. For a long time, metadata has been the way that most companies optimized content for retrieval, but now XML is beginning to make inroads into broader organizational content, and that brings all the benefits I’ve already discussed.

If you try and talk about XML, though, you’ll lose most managers because it is perceived as being too technical. However, you can turn it around and say we can create intelligent content that enables us to:

• More easily find it
• Deliver it
• Customize it
• Personalize it
• Automatically deliver it to multiple channels
• Simultaneously release content in multiple languages

And

• Reduce costs
• Speed up delivery time
• Optimize resources
• Do more with the same resources
• Increase customer satisfaction

We’re creating intelligent content that can be automatically discoverable, reusable, reconfigurable, and adaptable, etc. — we’re not just creating XML-based content.

What’s the role of the content creator in creating intelligent content?

The role of the content creator is crucial in intelligent content. It is not enough to just put our content in topics and push it out, although that’s a good start. We need to think about all the ways in which we can make our content adaptable. This means doing content analysis, customer needs analysis, and identifying an appropriate information architecture that sits above our content. Content creators are getting a good handle on DITA and structure, but very few use or understand metadata.

What kind of tools do you need to create intelligent content?

We can use the existing DITA tool sets and Component Content Management systems, but if we are interested in helping the organization beyond Tech Pubs, we should consider using XML content servers, and dynamic delivery engines.

What skills are needed for a writer to create smart content?

I’m always looking at where writers are today and where they can go to increase their skills and marketability, so this list reflects a growth curve. To start, writers should look at DITA, but in looking to the future they should gain an understanding of the following:

• Content modeling
• Metadata
• Reuse strategies
• Multichannel delivery strategies
• Mashups, pipes
• XPath and XQuery (not necessarily so they can code these, but so they know what they can do and specify requirements for them)
• Structuring content for marketing campaigns (the intricacies of campaigns are incredible and they are completely dependent upon intelligent content)

What organizations are employing tactics to make content intelligent?

We are seeing the beginnings of intelligent content with organizations that have moved to DITA, but organizations that are global or that have a broad product lines are really developing intelligent content. They are tagging content for region, product, audience, and more as well as automatically producing content that meets the needs of their customers. We have one client that creates 500 different pieces of content to reflect different products from the same content source, all automatically and all based on metadata tagging and DITA!

Next we are seeing intelligent content in organizations where their product is content (e.g., newspapers, magazines, publishers).

We are also seeing intelligent content in pharma, medical devices, intelligence, and financial industry organizations.

Ann Rockley is part of The Rockley Group, a content management company focused on intelligent content.

For more information about Ann Rockley, see The Rockley Group. You can also follow The Rockley blog.