Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
The rule in minimalist writing that requires you to keep your tasks to no more than seven steps can seem restrictive. In my experience, those procedures that may require more than seven steps are few. In fact, they are usually ‘one-of’ type procedures, such as maintenance procedures, setup procedures, and installation procedures. I am sure others exist as well but let’s just look at these.
Grouping Tasks in Maintenance Procedures
It is important to remember why we are even concerned about minimalism. Yes, it is easier to read and use but minimalism also evolved to serve the topic-based authoring we use to successfully create reusable chunks. So looked at from that perspective, go ahead and write your 17 step procedure. Now step back and look at that lengthy procedure:
- Are any of the steps describing a task that you perform in many maintenance procedures, such as opening a compartment where maintenance is performed? In that case, write that action as a single topic, Opening the Compartment, and refer to that topic as necessary in all procedures.
- Are any of the steps in this long procedure used in any other maintenance procedure, such as a troubleshooting procedure?
For example, let’s say you are writing a topic about changing the water bottle in an instrument. You have to remove and replace the water bottle to perform this procedure and the water bottle is in the aforementioned compartment. You have instructions for removing the water bottle and also instructions for replacing the water bottle. Even if this procedure were the only procedure for which you remove and replace a water bottle, I would still break those steps out into their own little topics. However, chances are, these tasks are performed for a myriad of other procedures.
You may also have to remove and replace the water bottle for troubleshooting an air leak or some cleaning procedure involving the water bottle. So, that gives you two more reusable topics: Removing the Water Bottle and Replacing the Water Bottle. Don’t forget, you may be able to reuse this information not just in another place in your document but on another instrument, as well. Having these topics as individual chunks is what makes reuse possible.
Okay, so now we have whittled out the task that we will definitely reuse, Opening the Compartment, and the steps that might be reused, Removing the Water Bottle and Replacing the Water Bottle. What are left are the steps necessary to do whatever you have to do to this water bottle. So you could have a procedure for Cleaning the Water Bottle, Checking the Water Bottle for Leaks, Refilling the Water Bottle. Actually, whatever you do to that poor water bottle is between you and your maker. In addition, all of these other tasks would refer to each separate topic as necessary. For example:
Cleaning the Water Bottle
- Open the compartment door. This is a link to Opening the Compartment. (4 steps)
- Remove the water bottle. This is a link to Removing the Water Bottle. (5 steps)
- Blah-blah clean. (1 step)
- Blah-blah dry. (1 step)
- Replace the water bottle. This is a link to Replacing the Water Bottle. (5 steps)
- Close the Compartment. This is a link to Closing the Compartment. (3 steps)
The intention of all this is to make the 17 step procedure into 3 or more reusable procedures and maybe a few ‘one-of’ procedures. That makes the 7-Step goal a little more feasible.
Grouping Tasks in Setup and Installation Procedures
Setup procedures are usually ‘one-of’ procedures. After the customer/operator/user has configured their system, they rarely revisit the area. Installation procedures are definitely ‘one-of’ procedures because once performed, they never-keeping our fingers crossed here-have to be performed again.
This does not mean you cannot or should not pity the poor person performing these procedures and continue to burden them with your mighty 17 step sections. No! But what is a writer to do?
Grouping Setup Procedures
Setup procedures are a bit easier to group in this respect. It is a matter of creating somewhat arbitrary groupings that you can write about. For example, with software configuration screens, you can write separate help for each screen. However, some of those screens could be so full of settings that you may need to mentally chunk the information on the screen and then write to those chunks.
I had one screen that I divided into 5 different groups for documentation purposes. This had the added benefit of making the parts of the screen more searchable in both online help and the hard-copy document index. I still had some tasks that pushed the 10 step boundaries but, hey, it was a one-time deal.
Grouping Installation Procedures
Installation procedures can be more problematic to group. Some installation instructions only involve putting the DVD in the drive and selecting Install. But, what if the instrument/device/operation you are writing about requires a service person to install it and to manage custom configurations along the way. I guess we could just tell the Installer that that is why they get the big bucks. They might give you an argument.
Obviously, you would break the procedures into the different sections of the installation but that still leaves you some sections seeming to require our possible 17 steps. This is where you can use chunking just as chunking, not necessarily with reuse in mind.
You do not have to worry about making each division in an installation into an individual topic. This is a ‘one-of’ and does not need real topic divisions. That is unless this installation procedure is similar to many other installations procedures used by all or most of the instruments or applications you are writing for. In that case, go crazy and create individual topics. It will serve you well.
Imagine the poor Field Service (FS) person, staring down lines of instructions, dividing her attention to watch instrument responses, and needing to go to lunch or the restroom or scratch her nose. This poor person needs to have logical breaks in the procedure where this can happen without losing her place. Inserting a new heading, still within the section, at a place where the tasks change even a little, can offer some hope of the 7 to 10 steps that are optimal.
Another ploy to consider is the procedure within a procedure. The simplest example of this is to look at tasks where the FS has to reboot-again. Start the each of those sections with its title and then do something like this:
- Sign in to the system:
- Enter your user name.
- Enter your password.
- Select Sign In.
- Open the compartment:
- Locate the door at the back of the instrument.
- Lift up the latch.
- Pull down on the handle.
- Enter the correct configuration bits for this installation:
- And so forth
Notice that you can cram a lot of steps into such a format. You do need to ensure you are not creating an artificial hierarchy. FS personnel are very logical and they will be thrown by an artificial hierarchy and make fun of you behind your back.
Also, notice that you could write the first step for reuse, EXCEPT in this situation. FS personnel are not paying any attention to your writing so they won’t care if it is repeated. They also don’t want to leave their current place on the page to find that oft repeated set of instructions. This FS may not even be the same FS person that started the installation if it is a multi person job. This is where knowing your audience, empathizing with your audience, is very, very important.
I like the step > substep structure illustrated in the example steps but it does have a pitfall: some users just don’t get it. This is not usually a problem with FS personnel but, in customer procedures, some customers cannot see past the Step to read on to the Substep. I have witnessed this in usability-testing sessions. The user reads the line “Open the compartment.” And then says, “I don’t know how to open the compartment.” In a total contravention of the rules of usability testing, you want to say something directly to the user-actually you want to scream at them-but the usability coordinator has taped your mouth shut.
Use some ingenuity and find out if you can keep your procedures down to 7 steps or at least 10 or less. It will not always be possible but we live in an imperfect world.
Learning minimalist techniques was a big excitement for me–once I quit fighting it. It is not hard to learn, just hard to do well at first. Once you get going with it, it becomes a challenge to include all necessary information without wasting a single word that doesn’t need to be there.
At The Technical Author, we try to explore minimalism, topic-based authoring, and structured authoring in equal measure. We also have a dandy list of Book Recommendations that can further your efforts as a steely-eyed, no nonsense tech writer.