Writing Procedures

I spent most of my tech writing days writing maintenance and operations procedures. Some simple guidelines:

One action per step.
When decisions are part of the procedure, use a format known as conditional logic.
Unless actually needful, avoid adverbs.
Warnings, Cautions, and Notes precede steps.
Warnings, Cautions, and Notes are presented in the order of importance.
Callouts are helpful with images.
Structure steps in the sequence needed to perform the action.

One action per step means avoiding the word and.

Conditional logic is similar to software programming: IF/WHEN some condition exists THEN do action.

An example when an adverb might be needful:

Slowly open the valve.

An example when an adverb is not needful:

Carefully measure the voltage.

The word carefully should be implied in a Warning preceding the step that high voltages exist.

The step structure should flow in the order of performance. For example:

Consider the following example.

Record the voltage at test points A and B of the sensor in the oven.

The structure requires the user to fully digest the entire step and read the step backwards.

Consider instead the following.

In the oven, at the sensor, at test points A and B, record the voltage.

The second example guides the user directly into the action.

Posted: November 14, 2020 Category: Usability Tagged: Tech Writing