Anthrobytes Media, LLC

In previous articles, I’ve covered the basics of procedures, how to identify and follow task paths, and how to chunk your procedures to let humans follow them. This post talks about long complex technical procedures in technical writing and knowledge management.

This (probably) last post covers what to do if you really have a long, multistep procedure. Procedures like this sometimes happen in knowledge management, especially if you’re having your reader set up a complicated system, such as integrating your product with AWS Kubernetes, or replacing the motor in their air conditioning unit. Some technical procedures are just long and complicated in technical writing and knowledge management.

Long procedures show up more in knowledge base articles but can appear in any technical writing or knowledge management documents. That’s because knowledge base articles are a slightly different kind of content.

Step 1: Identify the natural task pause points

All processes have natural pauses where the reader is done with a subtask. In a previous article, I mentioned chunks and these natural resting places can be thought of as meta-chunks.

These are when the reader is done with a screen, if you’re writing about software, or has removed the cover, if you’re writing about replacing the motor in the AC unit. The small task on the larger task path in the technical procedure is complete, and may require the reader to click Next or put down these tools and pick up a different set of tools.

Review the 100 steps of death in the knowledge base content you wrote and look for these natural resting places. When you see them, add a heading that identifies the goal of the smaller set of steps.

What should that heading say? It depends. If you have no standard for this, a great start is to name it the name of the subtask: Remove the AC Cover. It’s clear to the reader what subgoal this task does. Keep those words short and name the specific task that happens in this part of the larger task path.

Another great naming structure is what I did with the heading above. A caution here, though: do not number the steps if the entire process is going to have more than 10 chunks.

Step 2: What this looks like in technical writing

Now that we have the idea in our heads, what can this look like in a technical procedure? Here’s an example (you’ve seen this before if you’ve followed the series):

Step 1: Log into the BlobBlob system

1. Using your company username and password, go to [pretendURLlinkhere] and log into the BlobBlob system.
2. From the menu on the left, click Request Time off.
   (A screen capture here would be great.)

Step 2: Specify your vacation dates

1. Near the top of the page, click the Start date calendar icon.
   (A screen capture here would be great, including the items for step 1 and 3 circled or boxed.)
2. Select the date you want to start your time off. This is your first full day of vacation.
3. Click the End date calendar icon.
4. Select the date to end your time off. This is the last day you want to be away. The end date must be after the start date.
5. Review the dates to make sure these are the dates you want off.
6. When you’re ready, click Submit. You see a message on the screen.
7. Read the message and click OK. You return to the BlobBlob home page.

Step 3: Submit your request

1. From the menu on the left, click View pending time off. You see your pending requests.
   (A screen capture here would be great.)
2. Click the request you just made.
3. Review the dates to verify they’re correct. Then click Next.
4. On the next screen, complete the Reason for the request. You can type up to 300 characters, including spaces.
5. Click Next.
6. On the next screen, from the Approval list, select the name of your supervisor.
7. Click OK and then click Next.
8. On the next screen, verify the information about your request is accurate. If you need to make changes, click Update.
9. When you’re satisfied the information is correct, click Save and then click Submit. Your vacation request is sent to your supervisor for approval. You can see approved vacation days on the first screen when you log in.

Step 3: Let’s discuss

You can see the natural task resting places, or pauses, or meta-chunks in the steps above and the breaks I made with the new headings. For each set of steps in the knowledge base article, we’re in a new area of the product and doing the next chunk of steps with a specific task goal in mind. That task goal is the name of that task.

For example, Step 3: Submit your request includes the steps needed to submit the request, but only those steps.

A common objection I have heard is that customers may skip to step 3 and then try to do that set of steps. And that’s true. But we’ve done everything we can to help them see this entire set of technical procedures needs to be completed in order. We labeled the task pauses with step numbers and a heading.

Most people understand they can’t just jump to step 3 and start there. In this case, if they try, they quickly discover they have no way to do this because they’re not logged in.

Some procedures in technical writing, like replacing the AC motor, are very long and complicated and may occur over several days, for example. Readers can potentially lose their place in the overall technical procedures. You can help them by adding a non-numbered text after the heading that reminds them to complete the previous steps before starting this one.

For example, I can add:

Step 3: Submit your request

Now that you specified your vacation dates, you’re ready to submit your request.

Then the numbered steps start. The person doing the involved technical procedure can use this reminder of where they are in the overall process. Oh, yes, they can think, I’ve not specified the days I want yet. I should go do that.

Will it stop every person on the planet from jumping to step 3 and trying to start there? No. If you can figure out how to be clear to every person on the planet, reach out because I can’t wait to hear how you do it.

Step 4: Your thoughts?

Now that I’m just about done with how to write rock-your-world technical procedures, have I missed anything? What questions didn’t I answer? What edge cases have I not covered? Where am I wrong? What else do we need to think about in knowledge management and procedures?