A Project of
|Guidelines||Rants||Patterns||Poems||Services||Classes||Press||Blog||Resources||About Us||Site Map|
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.
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.
Help (A chapter from Hot Text: Web Writing that Works. PDF: 995K, or about 18 minutes at 56K).
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).
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)>
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.
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.
Example of this approach
Multiple operating systemsAfter
Deciding whether your computer should contain more than one operating system.
The process set is
Preparing for the Day.
Writing that Works!