TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Procedural Steps II From:Melissa Hunter-Kilmer <mhunterk -at- BNA -dot- COM> Date:Fri, 1 Nov 1996 09:41:19 EST
On Thu, 31 Oct 1996, the Doc. Goddess (Margaret Packman, mpackman -at- CISCO -dot- COM)
> Now I have a question on how to number steps within longer procedures. For
example, I have one procedure to document that's 47 steps long. I realize
that the obvious answer is for the engineers to make the procedure shorter,
but until that happens, I have broken it down to smaller chunks of 3-5
steps, with an header describing the overall step.
I've just written a chapter that had several procedures ranging from 55 to 97
steps long. The trainer on this project and I tried six ways to Sunday to
figure how to make the procedures more easily understood by clueless newbies.
We finally came up with several things that seem to be working.
First off, we start the chapter with the usual definitions, terms, etc. This
introductory matter includes a procedure summary (thank you, Conrad Gottfredson)
that gives a quick and dirty intro to the task. In this case, we broke down the
procedures into five chunks: getting into the app, creating or locating a
customer, entering non-product details of the order, entering product details,
and entering extra charges. We included a representative screen dump for each
chunk (though there is certainly more than one screen for each) and a summary of
steps that could be found in each chunk.
Then each procedure carried on with the chunk theme by grouping steps under the
chunks, which were labeled in bold reverse type in a black box -- for example,
Subtopic A: Getting into Order Entry. Within Subtopic A, steps are labeled A-1,
I really like the black box and reverse type. They make the subtopics stand out
and help the user to understand that this is not a daunting procedure, just one
with several major chunks to it.
We've gotten good reviews from end users.
mhunterk -at- bna -dot- com