IMPORTANT: This topic is about procedures. However, all of the following examples contain discussions of multiple subjects—not just procedures. Therefore, in addition to procedures, you are going to learn a lot of different things about good writing and rewriting.
Example 1
REWRITE THESE PROCEDURES
PROBLEM
- Word order—steps 1, 3, and 5.
- Multiple actions in one step—Step 2.
DISCUSSION
The Microsoft Manual of Style (MSTP) is the default style guide for the software industry. Unless your company has a different style guide (for example, I worked for HP for two years and they had their own style guide), use MSTP. MSTP makes recommendations about word order, but it does not make specific recommendations about multiple actions in a single step. However, for multiple actions, there might be a better way to communicate multiple actions in a single step by having a second level of steps.
This is what MSTP says about word order in procedures:
As a general rule, tell the user where the action should take place before describing the action to take.
This does not happen in steps 1, 3, and 5.
Step 1
Here is step 1:
Log in to the IRF fabric through the console port of any member switch.
First, we need to tell the user where the action takes place. The action begins at the console port of any member switch. Therefore, rewrite the step this way:
Through the console port of any member switch, log in to the IRF fabric.
Step 3
Here is step 3:
Use Telnet, web, or SNMP to access the IRF fabric from the network management station.
Rewrite:
From the network management station, use Telnet, web, or SNMP to access the IRF fabric.
Step 5
Here is step 5:
Show the running status of the IRF fabric by using the commands in Table 5.
Rewrite:
Using the commands in Table 5, show the running status of the IRF fabric.
Multiple Actions in a Single Step
Step 2 is OK as it is now. You don’t need to change it.
But instead of having multiple actions in a single step—making the sentence long and complicated—why not break out the multiple actions into a set of subordinate steps? The additional white space may make it easier for the user to follow instructions.
See the following screenshot:
REVISION
See the following screenshot:
Example 2
REWRITE THIS SET OF PROCEDURES
PROBLEM
A step is an imperative sentence—that is, a command. Descriptive text is a declarative sentence—that is, not a command or a step. Description and commands are two different things. Therefore, the format for a command is different from the format for descriptive text.
DISCUSSION
In the previous set of procedures, everything is formatted as a sequence of steps. We need to take the descriptive text out of its current format, and format the descriptive text as ordinary text amongst the steps.
These sentences are descriptive text:
- The library requires you add the following permissions to the manifest file.
- These are the required metadata declarations (see the onboarding process to get more information on obtaining about these values).
- We recommend putting the environment variable in the strings resource file.
- You can also set language and country preferences in metadata.
REVISION
See the following screenshot for the before set of procedures:
See the following screenshot for the after set of procedures:
Example 3
REWRITE THIS SENTENCE
PROBLEM
The example sentence is describing the three phases of configuring a switch. The sentence is too long.
DISCUSSION
You can rearrange it as a series of steps or you can write three short sentences with suitable transition words.
Let’s look at both solutions.
REVISION
Before
Configure a SUNRISE server to act as the CIRCLE server, add an account with the username hello@bbb on the CIRCLE server, and configure the CIRCLE server to assign the privilege level of 3 after the user passes authentication.
After
[three steps]
See the following screenshot for the after set of procedures:
Or
[short sentences]
Configure a SUNRISE server to act as the CIRCLE server. Add an account with the username hello@bbb on the CIRCLE server. Then configure the CIRCLE server to assign the privilege level of 3 after the user passes authentication.
Example 4
REWRITE STEP 2
PROBLEM
Step 2 has a mixture of procedural sentences and descriptive sentences. Know the difference. They are not the same thing.
Format the steps as steps. Format the descriptive sentences as ordinary sentences amid the steps.
DISCUSSION
These sentences are steps:
- Make a backup of the CMS database.
- Run the ConvertDBStructure.bat conversion script on the database server to convert the CMS database.
- Run the script on the machine that hosts the CMS.
- Execute the script without arguments to see the usage instructions for the conversion script.
These sentences are description:
- The script is located in the DoubleByte folder in the CMSDatabase.zip file.
- The script should be run alongside all the files and folders contained in the zip file.
- You cannot run it in isolation.
See the revised Step 2.
REVISION
See the following screenshot for the before and after set of procedures:
Example 5
REWRITE THESE PROCEDURES
PROBLEM
These are the problems:
- Use the infinitive verb form to lead into the procedures.
- Do one of the following:
- Put only one step per line.
- If you want to put more than one step per line, make it all one sentence using correct punctuation and connector words.
- Don’t use all caps for emphasis.
DISCUSSION
The main problem with the example six steps is the presence of more than one complete step for a separate line. This occurs in steps 1 through 5.
There are two acceptable ways to correct this problem. See the Revision section, and decide for yourself which revision looks best to you.
REVISION
See the following screenshot for the before and after set of procedures:
Example 6
REWRITE THIS STEP
PROBLEM
These problems:
- Fonts
- Parentheses
- Procedures
- Punctuation
- Usage
- Word Order
DISCUSSION
Fonts
FancyApp is a user interface (UI) feature. UI features are bold. Do not use quotation marks. However, in our rewritten step, we wrote the UI feature out of the sentence. That’s why the boldface FancyApp is not there.
Also note, when you refer to the FancyApp logo, the characters in FancyApp are not bold because we are talking about the logo itself, not a word on the UI.
Make Your Repositories bold. It is a button on the UI.
Parentheses
Never put a step in parentheses. Steps are too important to treat as an aside. Remember, text in parentheses is considered not as essential as the main sentence. That is not the case here.
Procedures
Rewrite,
Click the FancyApp logo to get there
as a standalone step.
Punctuation
Problems:
- Parentheses
- Single quotation marks
Usage
The word within is misused. The word in is correct in this context.
Word Order
See the revised sentence.
REVISION
See the following screenshot for the before and after set of procedures:
Example 7
REWRITE THIS SENTENCE
PROBLEM
This is a procedure formatted as descriptive text. We might consider formatting the information as steps.
If we leave it as descriptive text, my preference is to break it out into simple sentences to improve readability. However, it is probably OK to revise it as a long single sentence.
There is a spelling mistake. Did you notice it?
DISCUSSION
See the revision section.
REVISION
See the following screenshot for the before and after set of procedures:
Example 8
REWRITE THESE PROCEDURES
PROBLEM
This set of procedures has many problems:
- Capitalization
- Code in text
- Fonts
- Procedures
- Punctuation
- Usage
DISCUSSION
We are going to take it one line at a time.
Line 1
To add a domain user or group to a group on the server:
I am OK with this.
However, to be more formal, you could add this verbiage:
To add a domain user or group to a group on the server, do the following:
Line 2
Open Computer Management.
Computer Management is a user interface (UI) feature. It should be bold.
Open Computer Management.
Line 3
In the tree, navigate to System Tools\Local Users and Groups\Groups.
Change navigate to go.
In the tree, go to System Tools\Local Users and Groups\Groups.
Line 4
Double click the desired group and click Add.
Put a hyphen between double and click. Add a comma after the word group. Make the word Add bold because it is a UI feature.
Double-click the desired group, and click Add.
Line 5
Click Locations and then choose I want to complete this action by entering my credentials on the authentic Windows sign-in screen. Send ctrl-alt-delete to the server as asked, then authenticate with an account in the same domain as the user or group you want to add.
Do the following:
-
- Make Locations bold.
- Add a comma after the word Locations.
- Make the second sentence a separate step.
- Make ctrl-alt-delete Courier font and non-italic.
- Add the word and after the comma.
Click Locations, and then choose I want to complete this action by entering my credentials on the authentic Windows sign-in screen.
5. Send ctrl-alt-delete to the server as asked, and then authenticate with an account in the same domain as the user or group you want to add.
Line 6
NOTE: enter your username in the format DOMAIN\USERNAME.
Capitalize the word Enter.
NOTE: Enter your username in the format DOMAIN\USERNAME.
Line 7
Select your target domain in the Locations box and click OK.
The word Locations is a UI feature; make it bold. Add a comma after the word box.
Select your target domain in the Locations box, and click OK.
Line 8
Enter the user or group name in the box, then click Check Names. If you entered a name that matches a domain user or group, it is underlined. Click OK.
The sentence, “If you entered a name that matches a domain user or group, it is underlined” is not a step. Separate it from the previous sentence, which is a step.
The sentence, “Click OK” is a step. Make it a separate step in the set of procedures.
Enter the user or group name in the box, then click Check Names.
If you entered a name that matches a domain user or group, it is underlined.
8. Click OK.
Line 9
You should see your new user or group in the group members list. Click OK.
The first sentence is not a step. Make it descriptive text.
The second sentence is a step. Format it as a step.
You should see your new user or group in the group members list.
9. Click OK.
REVISION
See the following screenshot for the before and after set of procedures:
Example 9
REWRITE THIS STEP
PROBLEM
The example procedure actually contains three steps:
- Add the following script to your index.html page
- [make] the appropriate edits to variable declaration (var didConfig)
- [specify] your clientID and the paths to your responder page and your customized .css file, if it is implemented
DISCUSSION
Try to confine your steps to one action. Avoid individual procedures with multiple instructions.
REVISION
See the following screenshot for the before and after set of procedures:
Example 10
REWRITE THIS SENTENCE
PROBLEM
These issues:
- Present vs. future
- Procedures
- Wordiness
DISCUSSION
Present vs. Future
Don’t say this:
You will need to extract….
Say this:
Make sure you extract….
Or
Extract….
Procedures
When you say, You will need to extract, it sounds like you are giving nice-to-know information. However, when you give a procedure—which is what the author is doing here—phrase it as a command. See the Revision section for the rewritten version.
Say this:
Make sure you extract….
Or this:
Extract….
Wordiness
Don’t say this:
… all of the files located in the ZIP file
Say this:
… all the files in the ZIP file
REVISION
Before
You will need to extract all of the files located in that ZIP file.
After
Make sure you extract all the files in the ZIP file.
Or
Extract all the files in the ZIP file.
Example 11
REWRITE THIS STEP
PROBLEM
This is a run-on procedural step.
DISCUSSION
In my opinion, you have the flexibility to either make it two steps or make the second part of the example sentence a descriptive sentence that give more details about the step. I’ll show you both ways in the Revision section.
REVISION
See the following screenshot for the before and after set of procedures:
