Information Technology Reference
In-Depth Information
Independent?
“Purchase of these tools will give the IT staff the opportunity to
interact with other users of this technology.” (And why is this a benefit?)
The following two items, quoted or closely paraphrased from real documents, are
failures of good professional writing. The first is from a functional specification, and
is intended for a non-technical client.
Crucial user requirements as indicated in the task analysis (detail) phase
include:
A record-level mutex provision allowing long-duration transactions.
Rollback with user authorization and high-level “diff” display for
feedback.
Blackboard-based sharedworkspaceswith hierarchical access-control
protocols.
Arbitrary nesting of customized document elements.
Definition of customized elements in UI mode and plain-text mode
with full BNF-based error-checking on demand.
Write-on-demand and auto-write in both generic and customized
element creation environments.
It is difficult to see how a client could use this specification to give meaningful
feedback to the developers; I would guess that even experienced computing profes-
sionals would struggle to understand this specification, and would need to use their
imagination to see how the separate statements relate to each other.
The next example is from instructions written by a developer for users of a con-
figurable workflow system.
Modification of the interface to allow direct displaying of and modifica-
tion to currently-hidden fields can be done by performing changes to the
record-display screen module in the interface package. The key routine is the
advancedShowItems
routine which is used by administrators when low-
level changes need to be done to patch errors in stored data. Fields displayed
in the
advancedShowItems
routine are editable in a browser and changes
are performed in the database when “Save Record” is done by the user.
Three changes need to be done for the customization. The fields where
changes can be performed need to be fetched which involves changing the
SQL statement used to fetch records by adding the required fields. Then dis-
playing the fields need to be done using the same routine as existing fields (the
showEditableField
routine is used for this). This will break the layout
table which also needs to be modified. Then the final stage is to modify the
test statements so that modified fields are added to the update SQL statement.
These instructions ran to about 50 pages, all at this level of clarity. A developer who
used the system described the instructions as being, in most cases, a response to
