One topic keeps coming up in discussions about technical writing, and which bounces around in my head: What type of user docs should we create? The standard triumvirate is Conceptual, Procedural, Reference. But I’ve written that content as separate topics, as topics that contain two of the three, and even as topics that contain all three.
I have to warn you that I don’t have a definite answer. I doubt that one exists, but I believe that by addressing it, I’m improving the docs that I’m writing, and maybe getting closer to a solution. Although I suspect that the answer is a frustrating “It depends!”
C, R, and P
First: Separating conceptual from reference from procedural is easier for the writer, but doesn’t help the reader. Smoothing over differences in voice (from different authors, for example) is an easy problem to resolve. But I think that the transition from one form to another is, itself, the real problem.
I’ve spent a long time writing documentation with a lot of procedural components. I’ll start by explaining the task, what it is and why it’s interesting to the reader, what problems it solves, etc. And then, after that conceptual introduction, I have a series of numbered steps that lead the reader through a generalized version of the task. I’ll include example values and screenshots to help the user with navigation.
But the more that I talk to my readers, both internal and external, the more that I hear one thing repeated: “I don’t like long lists.” “I skim instructions like that.” “I read a bit and then try to figure it out myself.” (Or, of course: “There’s documentation for that?”)
So why do we (I) do it?
I’ve heard this enough times to become discouraged. Tech writers always joke (or half-joke) that no one reads what we write. But in this case, I keep hearing that users don’t want to read it. They know it’s there, but lists are so boring, and often too obvious. How many times have you written “Click Save to save the file”?
If anyone reading this isn’t a technical writer, I’ll let you in on a deeply held secret: Technical writers don’t want to write that. We hate it. It makes us cringe, and we feel a tiny part of our souls being chipped away every time we write something that head-smackingly obvious.
Fundamentally, we don’t trust our users. We assume that most of our users are intelligent people of good taste and sparkling wit. However, we also know that some percentage of our readers look back fondly on their days of eating paste straight from the jar and will scream most unkindly when they lose their work because we did not, explicitly and in great detail, tell them to press that damned Save button.
The dreaded v-word
These readers have also told me what they do want.
I’ll let the shock of that revelation subside a bit.
Ok, I know that you’re not surprised. Readers have been telling us this for years. We have come up with some good reasons why the users are wrong, why they don’t really know what they want, and why traditional documentation is much better.
But we need to accept that we’re in denial. And by “we,” I absolutely mean me. And I’ve created videos for documentation! I know how useful they can be. I created quite a few usage videos for artists who were learning to use a product that I was documenting because they told me that they just wanted to SEE how to use it. They wanted a quick demo video, a bit of text explanation, and that would be enough to get them going. They also appreciated written tips and tricks, but they really wanted those videos.
So it’s videos or nothing, right?
We know the disadvantages: It’s difficult to skip to a certain place in a video, it’s annoying to have to rewind to catch something that you missed, and for those of us creating videos, it’s torture to have to hear our own voices over and over as we edit the things.
I know it’s not just me.
The most appealing idea to me is to replace the beginner topics with short videos. Those are usually quick, and your novice users will appreciate the visual guidance to your product. It’s always easier to show a series of clicks than it is to describe in writing how to find a particular sub-menu that opens a dialog wherein you can find that specific checkbox.
Drawing a line. Although it’s a little wiggly, to be honest.
One thing that I won’t budge on: Reference info must be documented. API reference? Programmers want that written down. But even then, there are some nifty interactive tools that show them what they want when they want it. They read about, and test, specific values and ignore the fields that they don’t care about. I’m concerned that this might lead them to miss info because they just don’t see it, but I think it’s worse to overwhelm a reader with too much information and make them run screaming from detailed descriptions of a thousand options that they won’t use.
I’ve been working with the Apigee console. I’ve even implemented it in some documentation, but I wasn’t involved with the project long enough to know the actual usage stats.
Some writers are creating videos for reference topics. And I am very glad that they are, because I would have no idea where to start! (I’d add some links here, but damned if I can find them now.)
In general, though, when someone just wants to know allowable values, or possible outputs, or basic syntax format, it’s easier for them to refer to a written reference. If I’m looking up CSS parameters, I don’t want to deal with a video, even a short one, to figure out why my body text is 40 point bold Comic Sans.
Where does this get us?
I’m saying that building walls between conceptual, procedural, and reference-ural…er…reference information is an old and stodgy practice. Numbered lists that approach infinity are boring and make our readers turn elsewhere for information. They might just skip the docs entirely and push buttons until something works. Or they call the support team, who will tell you to fix your docs.
Short videos, narrated by humans (and not people doing their best Dr. Sbaitso impression) are great for all of those beginner topics that we hate writing, anyway.
I admit that my bias is showing: I’ve seen DITA done wrong; terribly, head-smacklingly wrong. But I hate the idea of documentation that’s so tightly structured that it becomes cookie-cutter predictable and boring and forces the writers to twist the content to fit into the little boxes.
But whatever method you work with, focus on conceptual info, use cases, and examples for your advanced users. They know how to save their files (even if they still forget to do it every now and then). They want to know what happens when they enable Advanced Theta Processing Sync, and how it makes their life better.
I’m already writing longer docs. I spent years preaching the gospel of Short Topics Are The True Path, probably as a reaction against really long manuals that I had been writing. Now I’m moving back towards longer, but not manual-sized, topics that provide a useful chunk of information. Making users bounce from one tiny topic to another just annoys them. And annoyed users don’t read your docs a second time.
And I do need to make more videos. I’ll let you know how that goes.