Web Writing That Works!

           A Project of
           The Communication Circle

Guidelines Rants Patterns Poems Services Classes Press Blog Resources About Us Site Map

HomeRants > How to organize a step-by-step procedure. > Articulate the strategic decision.



 

Create objects introducing the decision.

A decision is an action.

Example: Raising a decision to notice

Another way to force a decision

 

Articulate the strategic decision

Articulate a strategic decision as an active choice between sets of processes, based on an informed choice between results.

Experts know which process to do first, in order to start a particular set of processes, with the goal of getting a particular effect. Beginners don't even realize they need to make a decision.

Too many documents written by engineers and edited by technical communicators assume the reader knows the decisions that should be made, the processes that flow from each choice, and the ultimate consequences. But users need to reason back from the desired consequences to the processes needed, and from those, to the right choice at the start.

  • Point out why the user must make the decision.
  • Surface the alternative results an expert would consider first. These tend to be goals, or sets of goals. Then force the decision.
  • Once the user has decided on a certain approach, spell out the processes involved (ignoring all others), and showing how they lead to the results sought.

In this view, the decision is a choice between two or more process sets, each with component processes that flow together toward the end result.

Resources:

Probe your audiences--gently.

Help (A chapter from Hot Text: Web Writing that Works. PDF: 995K, or about 18 minutes at 56K).

 

 

Create objects introducing the decision.

1. Start with an Introduction object, explaining in broad terms why the user may have to make a decision, and what the choices are, roughly.

2. Create a Goalset or Results Scenario object for each different results someone might want. At the end of each of these objects, offer pointers or links to the relevant Process Set.

3. Create a Decision Module object, which summarizes the choices in detail, and, depending on the user's decision, points to a particular Process Set for that purpose.

4. Put together Process Set objects (units that contain a series of processes in approximately chronological order).

 

 

XML version

DTD for objects introducing the decision, describing alternative goals or results, clarifying the decision, and offering links to process sets.

<!ELEMENT decision.flow (introduction, decision.goal+, decision)>
<!ATTLIST decision.flow anchor ID #REQUIRED>
<!ELEMENT introduction (#PCDATA, button+)>
<!ATTLIST introduction anchor ID #REQUIRED>
<!ELEMENT button (#PCDATA)>
<!ATTLIST button target IDREF #REQUIRED>
<!ELEMENT decision.goal (#PCDATA, button+)>
<!ATTLIST decision.goal anchor ID #REQUIRED>
<!ELEMENT decision (#PCDATA, button+)>
<!ATTLIST decision anchor ID #REQUIRED>

A decision is an action.

You can force users to make a decision by including it as a step in a procedure, whether the decision is critical or casual.

  • The step announces the need to make a choice.
  • The choices appear as bulleted items under the step.

Such a procedure may appear at any scale.

In a configuration guide, you would be writing at a very high level. In an installation guide for a printer, the choices are quite specific.

Putting a decision into a procedure makes it clear that the user must make a choice, a fact often buried in the prose.

 

Example: Raising a decision to notice

Before

Lines of code mean little when you want to measure whether or not the team is making progress. Metrics can be a challenge. Developers may tend to give you what you want, even if you turn out to be measuring something other than progress toward the goal. Your choice of methods may be determined by downsider aspects more than upside ones, when faced with various methods of measuring work. Reuse of classes seems good, if practical; number of instances, OK, if needed. But lines of code does not make sense; developers just write more code, but you get nowhere nearer to your goal of a functioning application. Average days spent per class per programmer gives some measurement of work, though you don't know whether they are treading water or not. How many levels of classes have you developed today? This questions also encourages proliferation. But you need to decide about metrics.
After
1. Choose one of these methods to measure productivity.
  • Lines of code: a stupid measure that encourages overwriting
  • Average number of days spent per developer on each class: gives an idea of actual work, though not progress
  • Number of levels of classes developed: encourages proliferation of unneeded classes
  • Number of instances created: OK, if needed
  • Number of classes reused in different projects: most useful

2. To measure productivity, adopt team-wide policies.

  • To measure reuse, do the following ... (set of processes or procedures)
  • To use lines of code, levels of classes, or instances created, do the following ...
  • To use average number of days, do the following …

Another way to force a decision

State the choice to be made, then offer discussions of the factors that could influence the decision.

 

Example of this approach

Before

Multiple operating systems

Placing multiple operating systems on a single computer may lead to problems with the file systems, if they are not fully compatible. If you are contemplating putting several operating systems on the same computer, then consider whether you really need to. You may avoid headaches just by postponing the decision, or setting up separate computers. There are special considerations depending on what other operating system (such as Windows XP in another partition, Windows 2000 or Linux) you intend to put on the computer along with Windows XP, and you should consider the impact seriously before proceeding.

After
Deciding whether your computer should contain more than one operating system.

Here are some factors that could influence your decision.

General factors

  • Impact of multiple operating systems on file system compatibility
  • Degree of need: can this decision be postponed?

Specific factors

  • If you want to put together Windows XP and Linux
  • If you want to put together both Windows XP and Windows 2000
  • If you want multiple partitions with Windows XP
 

The process set is Preparing for the Day. 
I chose the process Shaving.
Now I am working my way through the procedure on Lathering Up.

 

Home | Guidelines | Rants | Patterns | Poems | Services | Classes | Press | Blog |
Resources | About Us | Site Map

Web Writing that Works!
http://www.WebWritingThatWorks.com
 © 2002-2004 Jonathan and Lisa Price
The Communication Circle
Discuss at HotText@yahoogroups.com
Email us directly at ThePrices@ThePrices.com
Order Hot Text (the book) from Amazon