This post isn't about the media that might convey technical content. It's about the nature of the content itself. One way to slice and dice technical content is into three categories: conceptual, reference, and procedural material. We'll talk about them in turn and then about the importance of distinguishing them and being aware of them. There are also, of course, things like diagrams and videos - but that's really getting more into media than into type of content. Before we proceed, a caveat.
When we say that content is conceptual, reference, or procedural, we don't mean that a topic or article is either conceptual, reference, or procedural, and ne'er the twain shall meet. Mark Barker, in Every Page Is Page One and elsewhere makes the point well that a topic is a topic and a type of content is a type of content. A topic might use several multiple types of content to do its job. Think of a recipe. Recipes always include a list of ingredients (reference) and a set of instructions (procedure). Sometimes they also include discussions about the dish to help a cook understand how it might fit into a meal (conceptual).
That's because the job of a recipe is not to give you steps or ingredients, but to help you prepare a dish that you will enjoy. To do that, you need more than just a list or some steps.
Please never write a topic and insist that it can only have steps and no overview because Ryan Haber wrote that there are basically three kinds of content and that you should keep them separated.
Do not get hamstrung by kinds of content and let them become rules unto themselves. But do not ignore them, either, and thereby make it hard for your users to find what they need.
So now about the kinds of content and why not to ignore them.
Suppose I have a topic called Managing Doodads that includes a (conceptual) overview about doodads and the kinds of management to which they are subject. After that, it has a series of procedures for the most common management tasks. All well and good. Suppose then after step 6 of the procedure to collapse a doodad I put in a tidbit that when collapsed, the doodad measures 3" x 6" x 4" and must never be stored next to a heat source. Great. The tidbit's probably useful there for people collapsing their doodads. But what about somebody who has a doodad that has been collapsed for years and just wants to pack it away? He can see that it's 3" x 6" x 4" well enough. If he looks up doodad warnings, will he find the tidbit there? If so, you have to maintain that warning in two places. What about when the cause for the warning goes away? Consider the examples below. The one on the left is more stream of consciousness. The one on the right shows an author who has put like content with like and call out very important bits.
Now the example above is a little contrived, but you can see the point. Like information should go with like. If you must insert a warning (conceptual) into the middle of steps (procedural), be sure to call it out. Highlight it red or something. That way, if seven pages later you need to write something like, "See the warning way back seven pages ago," it will at least jump out at people. The best thing would be to put the warning, still highlighted, up at the very top with the content that overviews doodads generally. That way, anybody learning about doodads will find it, and not just those who happen to be collapsing it.
Nor is a kind of content tightly bound to a kind of presentation. It might be useful to describe prerequisites (conceptual) as a bullet list, a format often used for referency stuff, to make it easier to refer to. Conceptual information might be organized into a table, often used for referency stuff. And for pity's sake, if you have a procedure with one step, just say the step. Don't make a numbered list with one step in it. That just looks dumb.
The Kinds of Content
Let's talk about each kind of content.
Conceptual content is not about a specific procedure for working with a thing. It's not about facts regarding the thing. It's more about the thing in itself and its relationship to a broader system. That sounds very abstract, but it's actually very concrete. This information usually contains the who, what, when, where, and most importantly, the why information about a thing. This content helps the user understand the thing. If the user understands the thing, very often the how information becomes intuitive or just details. For this reason, in my mind, conceptual content is often the most important.
Conceptual information often takes the form of overviews or introductions. Sometimes they take the form of longer documents more like white papers. They often include parts-within-a-whole diagrams like schemata, architectural diagrams, or workflows. Take a made-up example from a made-up administrator's guide.
Conceptual content doesn't usually include raw facts about things like how much wood is used to make a house or how many feet per second a projectile flies. It contains information explaining why a house is made of wood, why it's more valuable for being in a particular location, and so forth. Conceptual content is more likely to explain the effects of a projectile on its target than to tell you specifics about the range and velocity of a particular projectile. For that sort of information, we use reference material.
This kind of content isn't usually helpful in itself but rather fits into other content to answer other questions. For instance, a product specification might tell you that the television is 48" long and 27" tall. Great. So? Well, if you have information about the size and existing contents of a room, that tidbit becomes very helpful for deciding where to put the TV.
Parallelism is always important in technical writing but in no place more important than in reference material. Parallelism makes it possible for people quickly to scan and sort otherwise monotonous and even camouflaged information.
Because reference material is not meant to be read but to be occasionally used to look up a fact, its format should make quick consultation easy. Tables and bullet lists are often ideal for this use. Sometimes, even a list of paragraphs works, provided you do something to make quick reference easy. One example is putting the distinguishing topic of each paragraph into the very first words of the paragraph and boldfacing those words.
Reference content should be put in a location where people can find it. That's clear. But what people? Simple: the people that will need it. If a reference table only applies to one procedure, but it in the same article as that procedure or else someplace nearby. If it pertains to a whole set of articles, then it is best to make the reference content into its own article and put it in the same section of your content, so that people will quickly see it. You can also mention and link to the reference material in each article where it is important.
The next type of content that we need to discuss is procedural content: how-tos. How-tos should guide a user through a specific process. Here are some thoughts about procedure-type content, ascending from the most granular to the most overarching.
- Write in the second person imperative mood.
- Write in complete sentences with simple grammar.
- Keep the formatting simple but visually distinct from surrounding text.
- Avoid adjectives as much as possible. If writing the button will do, then do that. Don't write the big red button on the left if there is only one button. Someone will come along and change the color of the button and never tell you. Trust me. They will.
- Put any warnings far in advance of the step at which anything could go wrong for failure to heed the warning, like at the start of the procedure.
- Try to avoid writing things like, "then proceed to step 12." You may have to write such things, but if you can avoid it by breaking a procedure up into sub-procedures, each with a title, it will be easier for readers to follow along. It's better to write, "Step 1. Install your hard drive. For detailed instructions on installing a hard drive, see Installing a Hard Drive."
- Generally avoid putting conceptual information in the procedure. It will only get lost, buried in the steps. If the conceptual information could be useful anyplace outside of the procedure, it definitely should not live in the procedure. You might expose the info in multiple places, including your procedure... maybe. The practice is called single-sourcing. We'll talk more about that later.
- Procedural content need not be a list of steps. Sometimes, a procedure only has a single step with some caveats and warnings. In that case, simply write the step preceded by caveats or concerns. Other times, to-do points are all optional or the order doesn't matter. Bullet points make more sense than a numbered list in such cases.
A good UI, good controls, access control, or general context very often blocks access to unauthorized users. These same things often practically hold a user's hand through the actual steps to completion of even complicated tasks. In such cases, procedural steps fade in importance compared to conceptual content that tells a user why to bother.
Pulling It All Together
In this post, we've looked at the basic kinds of technical content. Keep them in your mind: conceptual, reference, and procedures. When you're writing a topic, for each line you write, ask yourself what kind of content you are writing. Keep like content together when possible and call out different content when not. Just that one exercise will help you to write and organize your writing more clearly. Clearer writing is writing that your users will be happy to use.