Latest posts by techwriter (see all)
- 15 Questions to Ask After You Finish a Technical Document Project - February 12, 2018
- THY’s Perfect Information Design - February 9, 2018
- Waterfall vs. Agile Models in Technical Documentation - February 7, 2018
Here is the anatomy of a technical editing process.
This ORIGINAL SENTENCE is from a software user’s guide:
“A prompt will occur prior to deletion that confirms the operator’s wish to delete the selected item and once confirmation occurs the deletion is made final.”
Here is a BETTER version:
“A warning message displays, prompting the operator to confirm the deletion of the selected item. Once the operator confirms, the deletion becomes final.”
1) Within a software context, a “prompt” does not “occur.”
Instead, the system “displays” one of the following three “messages” on the screen:
a) Information message (provides information about the results of a command without any buttons to click);
b) Warning message (prompts the user about the possible consequences of an action about to be taken and offers command buttons to click);
c) Critical message (informs a user about a situation that needs to be corrected before the intended action can be completed; no command buttons displayed).
2) The message does not “confirm the operator’s wish” but prompts the operator to confirm whether he or she wants to go ahead with the intended action.
3) Whenever possible, all technical procedures should be written in the present tense since the reader assumes that the way a system or software behaves is a current reality and not a future promise.
A SIMILAR ERROR
A similar sort of error occurs in technical writing when the writer projects other human qualities to a system.
For example, “the system wants you to enter your password first” is that kind of an error since a technical system does not have any human emotions and it really does not “want” anything.