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:Re: Another Newbie question about procedures From:mearro -at- msn -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 17 May 2005 13:10:54 -0600
Although several people have mentioned process, it doesn't seem that
others understand what's involved with documenting a procedure & how this
differs from other types of writing. There are some great online resources
about procedural & task writing (can't think of URLs offhand but try
googling). Since this is a newbie question, I think it's worthwhile to
provide some specifics here.
A procedure can be defined as a series of steps taken to accomplish an
end. As such, it's important to document all steps that are required to
accomplish that end. If it's necessary for users to click OK to accomplish
the stated goal, then click OK should be included. If Click OK is not
required, then it's a judgment call. An example of this would be if after
the task is completed, an informational screen displays a message
confirming that the process is complete. If by clicking OK you are *only*
closing this screen, then this "Click OK" is not really part of the
original procedure.
Now Cancel (the way most people have described it in this thread) would
serve to stop the procedure - to prevent the stated goal from being
accomplished. That is not part of the procedure & IMO should not be
included in the documented procedure. I really can't see the point of the
following type of step:
7) To complete XYZ procedure, click OK, or to not complete XYZ procedure,
click Cancel.
The second part of the above step is just plain unnecessary & what I would
consider needlessly confusing. [It's also poorly written but that's not
the point of this discussion.] While following a procedure, users have
several options to stop that procedure. This is true at different points
of a process. For every step, should we tell users to enter info or click
X (or Cancel) to end the process? Of course not. Why should we include
this info in the last step? Since many users scan steps as quickly as they
can, this is not only unnecessary but could easily be misread.
Mary
----------------
Carrie asked:
> When writing a procedure, can you presume that users know that the
> last stage is Click OK to confirm your settings,
> or should you tell them this.
> Furthermore, should one tell them click Cancel to leave the screen.
New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
