Introduction
Information Typing is a powerful and important content structuring technique for technical authors, but one that is commonly misunderstood and certainly under-applied. Well-typed content benefits both readers and writers by producing information that is easier to understand and use, focused within the domain, and reusable across output formats. In this article, we’ll look at the primary information types, examine some simple tests for determining what content goes where, and discover ways to reduce or eliminate redundant and unnecessary content.
What this Article ISN’T
This article may be a lot of things — semi-interesting, a bit too long, kind of fun, [insert your own adjective here], but there are three things it definitely is not:
1. Tool-centric: Information typing is a technique, not a technology. You can use information typing in any editor, environment, or authoring tool; it’s about how you logically structure the content, not about any features your preferred software may or may not have.
2. About DITA: DITA (Darwin Information Typing Architecture) is very much focused on information typing (it’s in the name, duh), but not vice versa. That is, while you must know information typing to understand DITA, you absolutely don’t have to know anything about DITA to use information typing.
3. Code-y: If you’ve read any of my other Medium articles (and if not, get yourself over there and do so posthaste!), you know that they’re generally code-y in nature. But not this one; here, we’ll talk about information typing without getting into any code at all. You’re welcome.
What is Information Typing?
Let’s begin with a definition. Now, I couldn’t find one comprehensive definition that (a) I really liked, (b) wasn’t tied to DITA, and (c) didn’t have a bunch of words I had to look up, so I wrote one that covers the important points.
Information typing is the identification, classification, and separation of content blocks (chunks) into discrete categories, where each category has a specific function, structure, and presentation in the content set.
This is the definition we’ll use in this article.
Untyped vs. Typed Content
Before looking at the solution, let’s first get a grasp of the problem: untyped content. When we write free-form, unstructured content, different kinds of information can end up pretty much anywhere in our document set, like this.
This is unfortunate for both readers and writers. Here, different kinds of content are delivered together, conflated into muddy, multiple-intent chunks that probably contain good information — if only you could tease it out.
Readers, searching for relevant information, miss structural clues in untyped content; they often arrive at pages not knowing what to expect, and must spend time reading some of the content just to determine whether the page even meets their needs.
Writers, trying to provide relevant information, lose consistency of use because any page might contain any type of content; they can easily and inadvertently create duplicate content, and will undoubtedly find it difficult to locate specific content during later maintenance.
But when we write well-typed content, each information type (don’t worry, we’ll cover the types in great, gory detail shortly) has its own page — or at least its own position in each page — in the document set, like this.
This clean, highly structured format is great for both readers and writers. Specific types of content are strictly and discretely delivered, consciously separated from other types. This approach has advantages all around.
Readers now have clear structural clues right in the content; they know what’s behind a link before they click it, which reduces searching, backtracking, and false starts from hitting “not exactly it” pages.
Writers now gain consistency and dependability based on format; pages have a standardized look and feel, duplicate content can be more easily avoided, and of course the improved structure simplifies later maintenance.
Let’s put it this way: As technical writers serving our readers, we strive for three informational goals: acquisition, comprehension, and retention. We want our readers to be able to find the right content, we want it to make sense when they read it, and we want them to remember it so they don’t have to come back all the time. Information typing is, frankly, a cheap and painless way to help achieve those goals.
Implementing information typing techniques does not require a giant change (I could say paradigm shift, but I really hate that phrase) in the way you write, it does not have a big learning curve, and it does not require any specific tool or technology other than your already-existing wetware. It only requires that you actively (I could say mindfully, but I hate that one too; thanks a lot, Gwyneth, ya wacko) consider what type of information you’re writing at any given time and take care to keep that type of content together, and separate it from the other types. It’s easy, productive, and everyone wins.
Topics
The basic unit of content in information typing is the topic. Bear in mind that “topic” in this sense is analogous to “subject”, and might refer to actual, physically separate pages, or it might just mean discrete content sections in a single page. Either way, we can talk about topics without depending on any specific development environment or publishing process.
Topics follow some general guidelines. A topic should contain only information that is essential for the reader to understand the current subject. A topic should contain only information that is pertinent to the current context. And, a topic should contain only links to related but non-essential information. Following these guidelines keeps topics clean, focused, and uncluttered.
All topics should follow those guidelines, but it’s the three types of topics themselves that are the heart of the matter. Let’s explore them next.
Information Types: CTR
Each topic is meant to contain one and only one information type: concept, task, or reference. Each type, as mentioned in the handy-dandy definition above, serves a single, specific purpose in the content delivery strategy.
Interestingly (I hope), it turns out that this sequence is exactly how our brains process information anyway, from background ideas through necessary steps to available details — in other words, we tend to consume subjects linearly, progressing from the general toward the specific. I can’t adjust a timing belt in an internal combustion engine without first knowing what it’s for and how it works, and I can’t do any fine-tuning without knowing how to do the initial setup.
In other words, without the concept information, the task steps have no context; and without the task steps, the optional tweaks don’t make sense. I need to understand the concepts to perform the task, and I need to be able to perform the task to grasp the effects of the reference details. Put those letters, CTR, in your head and keep them there. Concept > Task > Reference, kids — it’s what’s for dinner!
Let’s look at each information type in detail.
Concepts
Concept topics provide background information that answers “why” questions: Why is this important? Why should I use this? Why does this change things? A concept topic reveals the importance of the subject (typically a task), explains the effect or impact of the subject, and defines the prerequisite knowledge for tackling the subject. And, like all three topic types, it links to related information — which, for concept topics, is task and reference content.
Tasks
Task topics provide ordered, step-wise information that answers “how” questions: How do I accomplish this task? How does it affect the overall process? How do I know if I did it right? A task topic provides a brief lead-in to the task, lists the enumerated steps of the task, and exposes intermediate results of certain steps (as needed) and the final result of the correctly-performed task. Of course, it also links to related information — notice that for a task topic, they are concept and reference.
Reference
Reference topics provide backup, customization information that answers “what” questions: What options are available? What are the requirements or restrictions? What details can I change to get different results? A reference topic briefly provides detail or examples without explanation or exposition, describes the requirements or restrictions on input, exposes flags or parameters that can be modified, and potentially lists common errors. And, naturally, it links to related concept and task information.
A Quick Refresher
Let’s revisit our definition of information typing from earlier in the article.
The key words are highlighted because it’s important to remember that each information type (a) performs a specific job in the document set, (b) follows a specific internal arrangement, and (c) exhibits a specific stylistic layout.
Now, you might think that this seemingly straightforward technique for structuring content would be fairly easy to implement for new information — and you’d be right (gotcha!). No, seriously, as you write new content, it’s quite simple to apply the mental filter of “type” and put the different kinds of information where they need to go. Easy-peasy.
But meanwhile, back in the real world…
Legacy Content
Applying good information typing to legacy documentation can be, let’s say, challenging. Legacy docs are usually linear and untyped, and nearly always mix information types in the same paragraph — if not in the same sentence! This is equally true for documents written by others and for our own older content. The information in existing content is often frustratingly, sometimes maddeningly (lookin’ at you, developers), conflated. It’s like serving a bowl of chili with strawberries and M&Ms mixed in — if you only want one of those things, you can’t get to it without messily picking through the other two.
Some legacy content is relatively easy to fix. For example, here’s a muddled topic that contains all three information types… somewhere.
This is ostensibly a task — at least, we can guess that it’s meant to be one from the title and the numbered steps — but it also contains generous helpings of concept and reference information just mixed in anyoldwhere.
Let me emphasize again that this is a problem both for readers, who can’t find the specific information they need, and for writers, who can’t effectively maintain the information later.
Fortunately, this topic is reasonably easy to parse for rewriting. Here’s a simple trick to help work out what’s what in a messy topic: just color-code the text so we can extract it into appropriate topic types. Using the simple RGB computer color scheme that we’re all, ahem, intimately familiar with, let’s colorize that text so we can tell what’s what. We’ll just keep the familiar letter order and use red for concepts, green for tasks, and blue for reference: RGB = CTR, get it? A quick markup job yields this.
Aha! It’s suddenly easy to see the basic information types and how they’re argle-bargled up in this topic. Now we can extract the useful content chunks of each type and put them into their own topics (which, recall, might just be a specific section of a single page) for easy reader consumption and low-anxiety maintenance.
Sure, that topic isn’t great, but some legacy content isn’t even that good. Here’s a topic that’s messier than Russell Brand’s hair. (I know, early 2000s reference; deal with it.)
Again, this ostensibly-a-task topic may contain valuable content, but it’s really hard to suss out and probably needs a complete rewrite. Still, you can try to apply the RGB trick to it to identify and extract some of the content. Save whatever can be accurately typed and put it into new topics, nuke whatever can’t be typed, then edit what you were able to salvage and write new content — of the correct type, please! — around it.
You might end up with something like this.
That’s often about the best you can do. It does, however, bring up another important tenet of information typing.
If the information you’re writing/editing does not cleanly and obviously fit into the concept, task, or reference type, then chances are good your readers don’t need it and you can remove it without consequence. In other words, “If it doesn’t fit, you must omit!” (Ooo, wicked mid-1990s reference; look it up.)
One More Thing
In the above examples, particularly in the “Related topics” links, I’ve implied that CTR is basically a 1:1:1 situation; while that’s comfortable for initial learning and discussion, it’s often not the case in practice. For example:
- Concept topics nearly always support multiple tasks; think how many individual tasks the concept “What is a Core Meltdown?” might support.
- Task content often leads to multiple reference topics; think of the many reference pages the task topic “How to Improve Page Load Time” might link to.
- Reference topics frequently lead back to both multiple tasks and concepts; think of the many concept and task topics that might be clarified and expounded upon by the reference topic “Musical Key Transposition Techniques”.
The bottom line is that it’s not a 1:1:1 deal; every topic should link to exactly as many others as necessary, whether that’s one or a hundred. (Okay, probably not a hundred, but you get my point.)
A great way to determine exactly what should link where is to use something called a relationship table, but that’s an article for another time. Let me know if you’d like me to write it!
Best Practice
The most efficient way to approach information typing in both new and legacy content is to base everything around the tasks. By identifying and developing clean task content first, you necessarily expose both the concept and the reference material needed to support it. You won’t have to go looking for the background and tweaking info; it will jump out at you as you work through the task info. Take notes or create stub topics for the other info types and you’re already ahead of the game.
As a bonus, tasks are typically the most critical information type to both users and management, so if either/both are pushing for ASAP content, writing task content is a good place to start — it produces the most needed and most useful topics first thing out of the gate and is no way wasted effort, as you’ll use those exact tasks later as a jumping off point for writing the concept and reference material.
Once again, this technique can easily be applied to single-page topics where you want to include all three content types. Just structure them top-down in that order (always!): first concept, then task, then reference. This structure logically leads readers through what they need to know and, significantly, lets them stop and bail out as soon as they’ve found what they came for. Every time you write a page, think CTR, CTR, CTR; both you and your readers will benefit.
Now, it has been argued that many readers won’t need the concept information; they’ll already know why they’re at the page and will already have some background on the subject/task, so we should just skip the concept stuff and get right to the task steps. That’s a fair argument, and my rebuttal is yes, but not everyone is a friggin’ whiz kid who knows what they’re doing before they do it; there will always be some portion of your readers who need the concept information, so omitting it really does them a disservice. What to do?!?
An excellent compromise was suggested by my colleague, the awesome Aussie tech writer Kate Jeffreys. Kate recommended that concept information should always be written and available, but that readers should not be required to wade through it in order to get to the task or reference info. Her clever solution is to make the concept material available at the top of the page (that is, first, where it should be), but initially hidden. Then, just make it easy to access through a prominent link that triggers a clever display device such as an expanding/collapsing div, a slide-in/dropdown panel, or a scrollable overlay. In that way, every user can access the concepts if they want, but no user is forced to view it if they don’t. Problem solved. Ta, Kate!
Summary
Let’s go home. To summarize, here are some things that information typing most definitely is:
- Well-named: you assign specific types to units of information
- Not a technology: it’s a content management technique that can be applied anywhere
- Not tool-specific: can be used with any editor, environment, or process
- Win-win: writers and readers both benefit from well-typed content
- Very conducive to saving time, effort, and money
- Easier with new content, but still applicable to legacy docs
- An invaluable skill for technical writers/content creators
Thanks!
Thank you for reading this article; I hope you had fun and learned something along the way! Comments or questions? Contact the author, Dave Gash, at dave@davegash.com.
