Recently I participated in a structured brainstorming activity with some technical communication colleagues. For those who don't know, I am a technical writer by profession, and I regard project management as a competency (in other words, project management is not my day job). At this activity, a fellow participant repeatedly made the point that "our jobs (as technical communicators) would be easier if things just worked the way they should." I could not disagree with this sentiment, but it's just part of the puzzle.
Very broadly speaking, I believe there are two distinct intents of computer documentation:
- Remedial intents
- Aspirational intents
Remedial content includes everything that tries to resolve a user's current problem--and the user knows they have a problem. Such issues can range from minor to show-stopper. A simple spectrum I like to use is:
- Speed bump: I encountered a problem but immediately came up with a work-around
- Puzzler: I encountered a problem that required me to rethink my current intent, or shift focus from my immediate task to research a resolution.
- Show-stopper: I encountered a problem that has stopped me in my tracks. I have no idea how to proceed.
Here are some Microsoft Project-specific examples of these three levels of issues:
- Speed bump: The new ribbon UI has moved several of my favorite commands, but the keyboard shortcuts for these commands have not changed and I'll use those as I become familiar with the new UI.
- Puzzler: I know that task types effect how Project recalculates the schedule. How specifically does it do so?
- Show-stopper: I cannot figure out how to create the task dependencies I want without exceeding the finish date deadline I need to meet.
As you can see, these examples range from minor to severe. There are many other examples of all three levels of problems I could add to this list, and probably so could you.
The technical documentation solutions to all three levels of issues above can be summarized as "troubleshooting" or "break/fix" and what such solutions have in common is this: move the user from a current state of frustration with Project to a better state. The specific formats of these doc solutions might be enumerated procedures (how-to), conceptual explanations, sample data files, videos, or many other possibilities. The format matters less than meeting the intent of the user who is, let's keep in mind, currently unhappy.
Such content is often what we mean when we refer broadly to computer documentation, but it's by no means the whole story. Another category to consider is what I call aspirational content. Such content is designed not so much to solve specific and known current-state problems. Instead, aspirational content aims to develop the user's skillset with the subject in a structured manner. A tutorial (like Project Step by Step) is a great example of aspirational content. So is any content that generally has a tone of "hey, did you know that you could..." Along the way aspirational content might provide many remedial answers to problems and frustrations the user brings to the content, but aspirational content is not designed to do so (or at least it's not optimized to do so). Again, I'll refer to the tutorial format. In the case of Project Step by Step, the information design asks the user to do some rather unusual things. These include:
- Pretend you are a project manager at a fictitious book publisher (that's the scenario we use in our book)
- Don't use your real-world Project data, but instead use our fictional data files, which are probably completely unrelated to your industry
- Spend many hours completing the activities in the tutorial, which, again, is all a fictitious scenario
In other words, this is scenario-based training. Do this in a classroom and we all recognize it as training. Do this on your own time and it remains training. Great training content makes its users (or readers, or students) themselves great general-purpose problem solvers in the subject area of the material.
While remedial content generally addresses the user's next few seconds or minutes of their work, aspirational content aims to affect the user's success with the subject of the material on the scale of months, years, or a lifetime. As a technical communicator, this is the most compelling focus I can hope for.