Procedural & Instructional Writing

When the only person who knows how it is done is the person who does it, every question comes back to them.

I turn expert knowledge, demonstrations, transcripts, and rough notes into instructions people can follow without asking the expert again.

  • Procedure design
  • SOPs
  • Training guides
  • Reference material
  • SME interviewing

Subject expertise stays with the expert. Documentation expertise stays with me.

Why this craft matters

This page is the writing craft behind the systems on the rest of this site. The same discipline that produced the product and support documentation in the case studies is shown here at sentence level: What a raw expert explanation leaves open, and what a written procedure closes.

The business case is simple. Knowledge that lives only in an expert costs the expert's time on every repeat question, puts quality at the mercy of who is available, and walks out the door when they do. A procedure a reader can follow without help converts that dependency into an asset: The expert answers once, the answer holds, and training, quality, and coverage stop depending on one person's calendar.

Everything below is a worked demonstration of how that conversion happens, using a constructed field-service example.

People keep asking the same questions

One source, and the document built from it, in five steps. The second step is the work. Anyone can retype a transcript.

Constructed demonstration

The source is fictional; the method is the one I use.

01Raw expert explanation

Spoken explanation. No formal procedure supplied.

Right so the belt, you check it every couple of weeks, more if the machine's been running hot. Pop the guard off first, obviously kill the power at the isolator before you go anywhere near it. Push down in the middle of the span with your thumb and see how far the drive belt gives. Should be about right, you'll feel when it's correct, too tight is worse than too loose. If the vee needs pulling up you slacken the four bolts on the motor foot and lever it back, then nip them up again. Don't do it with the machine turning, that's just common sense. Give the band a look for cracks while you're in there.

02What I found

Six findings. Each one is a decision the source leaves open.

01 Buried prerequisite

The isolation step arrives mid-sentence as an aside, and it is the first prerequisite of the whole task.

02 Unspecified equipment

The source names a thumb, a guard, and four bolts. It gives no gauge, no spanner size, and no belt identification.

03 Incomplete sequence

Order is implied by “then”, with no defined start point and no stop point.

04 Judgment as instruction

Experience-based judgment appears as a step. It is either a permitted variation or an observable criterion.

05 Safety gap

One safety statement gives no consequence and names no owner, so it returns flagged Safety verify.

06 Terminology drift

The source names one component four ways, and the document needs one approved term.

03Rewritten procedure

MNT-07: Drive belt tension check

Purpose

Confirm that drive belt tension is inside the approved deflection figure.

Added structure

Before you begin

  1. Set the machine isolator to OFF and apply your personal lock and tag.
  2. Confirm that the drive has stopped.
  3. Obtain the approved deflection figure from the machine data sheet.

Materials

  • Tension gauge, 0 N to 100 N.
  • Steel rule, 300 mm.
  • Combination spanner, 17 mm.

Added control

WARNING: Do not remove the belt guard until the isolator is locked off. A drive that starts during the check pulls fingers into the pulley nip. Safety verify

Procedure

  1. Remove the belt guard.
  2. Inspect the full length of the drive belt for cracks.
  3. Measure the distance between the two pulley centres with the steel rule.
  4. Apply 20 N to the centre of the drive belt span with the tension gauge.
  5. Read the deflection from the tension gauge.
  6. Refit the belt guard. Remove your lock and tag from the isolator.

Needs SME approval

What to observe

  • Step 2: The drive belt surface is continuous, with no crack across a rib.
  • Step 5: Deflection measures 1.5 mm for each 100 mm of centre distance. SME verify
  • A deflection outside this figure requires adjustment before the machine returns to service. Use procedure ADJ-04.

Variations

  • Check interval is a permitted judgment. The standard interval is 14 days. Reduce it to 7 days when the machine runs above its rated duty.
  • The deflection figure is a requirement. It stays the same whatever the machine condition, the operator preference, or the age of the drive belt.

04What changed, counted

These count the contents of the sample above and below. They are not client results.

Criterion Source Written output
Document identity 7unnumbered sentences 1titled, referenced procedure
Numbered steps 0 6
Stated prerequisites 0 3
Tools given a specification 0 3
Names for one component 4 1
Safety statements with a consequence 0 1
Measurable acceptance criteria 0 1

05Questions returned to the SME

Nine questions the source raises and cannot answer. Every question returned is a decision the client keeps.

  1. What is the approved deflection figure for this drive belt, and which document holds it?
  2. Is 20 N the specified test force, or is it the force this gauge applies?
  3. Does the deflection figure change with belt width, belt type, or centre distance?
  4. What is the tightening torque for the four motor foot bolts?
  5. Which crack pattern requires belt replacement, and which is acceptable wear?
  6. What is the required check interval, and which running condition shortens it?
  7. Which findings require the machine to stay out of service until maintenance attends?
  8. Who is qualified to adjust drive belt tension, and does that need a signed authorisation?
  9. Which tools are approved for this task, and is an adjustable spanner permitted?
What changed

A remembered feel became a figure any technician reads off a gauge. The isolation step moved from an aside in the middle to prerequisite 1.

Five more problems, five full samples

Each row names a problem in the client’s words and shows one line of the source beside one line of the result. Three of them open the same five-step treatment as the sample above.

Operations documentation

“Two staff do the same job two different ways”

Standard operating procedure

The cost: Rework, damaged equipment, late starts.

Source Shutting down: just make sure the line's safe.
Written 1. Return every tool to the shadow board.

“Two staff do the same job two different ways”

Standard operating procedure
Constructed demonstration

The source is fictional; the method is the one I use.

01Raw expert explanation

Email from the shift supervisor. No formal procedure supplied.

Shutting down: just make sure the line's safe and the next shift isn't walking into a mess. Tools go back on the shadow board, not left in the machine (we lost a torque wrench inside a housing last month and it cost us a full day). Close the guard, run the purge cycle, hit stop on the panel. The panel sometimes shows READY even after a proper stop, so watch the main contactor light instead. Fridays you also drain the coolant sump and log the hours. Handover sheet goes in the tray, supervisor login is on the laminated card by the kettle if you need to close the shift off in the system.

02What I found

01 Two procedures in one

Daily shutdown and end-of-week shutdown share a paragraph, so the two Friday tasks read as background detail.

02 Conditions in prose

Conditional logic sits in prose. Conditions belong in a table, where a reader checks one column and stops.

03 Defect mixed into routine

A known equipment defect sits among the routine steps. It is the verification step for the whole shutdown.

04 Credential in the document

A credential lives in the source. The SOP names the person who grants access, and it never carries the account.

05 Consequence worth keeping

The reason for the tool rule earns compliance, so it stays as a stated consequence on its own step.

03Rewritten procedure

SOP-12: End-of-shift shutdown and handover

Added structure

Scope

Applies to the operator who runs the last shift of the day on line 2.

Frequency

Every shift end.

Steps

  1. Return every tool to the shadow board.

    CAUTION: A tool left inside a machine housing damages the machine on the next start. One loss last quarter cost a full production day.

  2. Close the machine guard.
  3. Start the purge cycle. Wait for the cycle to finish.
  4. Press STOP on the control panel.
  5. Confirm that the main contactor light is off.
  6. Set the machine isolator to OFF.
  7. Complete the handover sheet. Place it in the handover tray.

Added control

Conditional steps

ConditionAdditional step
Shift is the last of the weekDrain the coolant sump. Record the machine hours on the handover sheet.
The shift is closed off in the production systemSign in with your own account. Request access from the shift supervisor.

What to observe

  • Step 5: The main contactor light is off. Use this light as the shutdown check. The panel display shows READY after a valid stop on some units.

Troubleshooting

  • Main contactor light stays on after step 4: Set the machine isolator to OFF. Report the machine to the shift supervisor before the next shift.

04What changed, counted

Criterion Source Written output
Numbered steps 0 7
Conditional rules 2written in prose 2in a table
Verification steps 0 1
Troubleshooting entries 0 1
Credentials in the document 1 0
Consequences stated 1 1

05Questions returned to the SME

  1. Which production system account grants shift-close access, and who approves the request?
  2. Does the purge cycle run for a fixed time, or does it end on a signal the operator watches for?
  3. Which machines on line 2 does this SOP cover, and which are excluded?
  4. Is the panel display fault present on every unit, or only on identified serial numbers?
  5. Who signs the handover sheet, and how long is it retained?
  6. What happens to the handover when the next shift starts on another day?
What changed

The Friday tasks left the prose and became a condition table. The panel quirk that every long-serving operator already knew became step 5, where a new operator finds it.

“Every trainer teaches it differently”

Training guide module

The cost: Certification cannot be defended.

Source Take as long as they need on it.
Written 90 minutes. Extend to 120 minutes for intakes of more than 8.

“Every trainer teaches it differently”

Training guide module
Constructed demonstration

The source is fictional; the method is the one I use.

01Raw expert explanation

Trainer’s course notes. No formal module supplied.

Module 2 is isolation and lockout. This one really matters, they can't go on the floor until they've got it. Take as long as they need on it. Usually I walk them through it on the training rig first then let them try it, then we go round the room and talk about it. Bigger intakes take longer. By the end they should understand isolation and be confident doing a lockout. Things that go wrong: they forget the stored energy, they use someone else's lock, they tag without locking. There's a lock kit somewhere in the cabinet.

02What I found

01 No measurable outcome

“Understand isolation” and “be confident” cannot be observed, scored, or signed off by an assessor.

02 Timing removed

The source gives no duration, then adds an instruction that removes timing altogether.

03 Sequence hedged as optional

A real teaching sequence is present, unnumbered and hedged as “usually”, so it reads as one trainer’s preference.

04 Best content placed last

Three known error patterns are the most valuable content in the source, and they sit at the end.

05 Unlocated asset

One teaching asset has no recorded home, so it is logged as Source required.

03Rewritten procedure

Module 2: Isolation and lockout

Added structure

Duration

90 minutes. Extend to 120 minutes for intakes of more than 8 technicians.

Prerequisite

The technician completed module 1 and holds a current site induction.

Learning outcomes

By the end of this module, the technician can:

  1. Name the four energy sources that require isolation on the training rig.
  2. Apply a personal lock and tag to an isolator in the correct order.
  3. Prove a zero-energy state before work starts.
  4. State the one condition that permits removal of another person’s lock.

Added control

Instructor sequence

  1. Demonstrate a full isolation on the training rig. Name each energy source as you isolate it. (20 min)
  2. Have each technician isolate the rig alone. Observe and score. (40 min)
  3. Correct faults individually. Use the fault table below. (15 min)
  4. Run a group review of the faults you observed. (15 min)

Fault table

FaultWhat to say
Stored energy is left in the system“Name every source that can move this machine. Prove each one is dead.”
A shared or spare lock is used“The lock carries your name. Only your key opens it.”
A tag is applied without a lock“A tag is a message. A lock is the control. Fit both.”

Needs SME approval

Materials

  • Training rig, isolation configuration Safety verify
  • One personal lock and tag per technician.
  • Lock kit, module 2 Source required

04What changed, counted

Criterion Source Written output
Assessable outcomes 0 4
Planned durations 0 1with one documented extension
Numbered instructor steps 0 4each timed
Faults named 3 3
Documented responses to those faults 0 3
Materials with a stated location 0 32 of them flagged

05Questions returned to the SME

  1. Which four energy sources does the training rig present, and does the floor equipment present the same four?
  2. What is the pass mark for this module, and who is qualified to score it?
  3. Which single condition permits removal of another person’s lock, and who authorises it?
  4. Does the 120-minute extension depend on intake size, on prior experience, or on both?
  5. How long does a module 2 result stay valid before requalification?
  6. Where is the module 2 lock kit held, and who maintains it?
What changed

Four scorable outcomes and a 90-minute timed sequence replaced “take as long as they need”. The trainer’s fault list moved to the front and gained the exact words to say.

“Nobody can find the answer, so they guess”

Reference material

The cost: Damage, and repeated questions.

Source wait a bit and they usually clear themselves.
Written Wait 60 seconds for the code to clear.

“Nobody can find the answer, so they guess”

Reference material
Constructed demonstration

The source is fictional; the method is the one I use.

01Raw expert explanation

Compiled notes from several suppliers. No single reference supplied.

Codes: E1 and E2 are pressure, wait a bit and they usually clear themselves. E3 is pressure too but that one's a stop. F codes are the sensor ones, wipe the lens and reset, if it keeps coming back it's the sensor. A1 is the door, A2 is the door as well but on the older units it's the interlock instead. Anything with a dot after it is a repeat fault. Most of this is either the supply pressure being low or the lens being dirty, honestly. Reset is hold the two buttons for a bit.

02What I found

01 Lookup content as prose

Three code families with three different rules arrive as one run-on paragraph.

02 Undefined quantities

Every quantity in the source is undefined, from the wait to the reset.

03 Shared causes placed last

Two causes explain most of the list. They belong above the table, where they answer the question first.

04 Two questions mixed

“What does this code mean” and “what do I do now” are separate columns for a reader at a stopped machine.

05 Undecidable distinction

One code behaves differently on earlier units, with no way to tell which unit is present. Flagged SME verify.

03Rewritten procedure

Fault code quick reference

Added control

Two causes account for most codes on this machine

  • Supply pressure below the set minimum triggers every E code. Check the gauge at the inlet before you do anything else.
  • A dirty sensor lens triggers every F code. Clean the sensor lens with a dry lint-free cloth before you replace any part.

Read a code with a dot after it as a repeat of the same fault. A repeat fault goes to maintenance, whatever the code says.

Added structure

CodeWhat it meansFirst actionMachine stops
E1Inlet pressure below minimumWait 60 seconds for the code to clearNo
E2Pressure loss during the cycleWait 60 seconds for the code to clearNo
E3Pressure loss with the head downSet the isolator to OFF. Call maintenanceYes
F1Position sensor blockedClean the sensor lens. ResetNo
F2Position sensor gives no signalClean the sensor lens. ResetNo
A1Door opened during the cycleClose the door. ResetYes
A2 SME verifyDoor opened, or interlock fault on earlier unitsClose the door. ResetYes

Needs SME approval

The stop column states which faults hold the machine until maintenance attends. Confirm the full list with the maintenance engineer. Safety verify

Reset

Hold the START and RESET buttons together for 5 seconds.

Escalate to maintenance when

  • The same code appears twice in one shift.
  • A code appears with a dot after it.
  • The code is E3.

04What changed, counted

Criterion Source Written output
Codes described 7 7
Codes in a lookup structure 0 74 columns each
Undefined quantities 4 0
Shared causes stated up front 0 2
Escalation rules 0 3

05Questions returned to the SME

  1. Which serial numbers count as earlier units for the A2 code?
  2. What is the set minimum for inlet pressure, and where does an operator read it?
  3. Does the 60-second wait apply to E1 and E2 equally, and what happens at the end of it?
  4. Which faults hold the machine until maintenance attends, besides E3?
  5. Does the machine generate the dot suffix, or does the person logging the fault add it?
  6. Which codes exist besides the seven listed, and where is the full list held?
What changed

A five-second lookup replaced a paragraph an operator had to read to the end. The two causes behind most of the list moved above the table, where they answer the question first.

“We have a manual and people still ask”

Manual front matter

The cost: The manual gets blamed, then ignored.

Source It's written for anyone who works with the machines.
Written Technicians who hold a current site induction.

“We have a manual and people still ask”

Manual front matter
Constructed demonstration

The source is fictional; the method is the one I use.

Raw source · draft introduction

Welcome to the operations manual. This document is the product of a lot of experience on this equipment and we hope it serves you well. It's written for anyone who works with the machines, whether you're brand new or you've been here twenty years. Dip in wherever you like, though we'd suggest working through it front to back. Obviously this doesn't replace your site safety rules and you should always use your judgment on the floor. Some of this reflects how we do things here, which may not match other sites. Good luck out there!

What I found

  • No audience. “Anyone who works with the machines” gives a first-week technician and a twenty-year fitter the same instruction. The manual then has to serve both at once.
  • Contradictory navigation instruction. “Dip in wherever you like” and “work through it front to back” cannot both be the rule.
  • The scope limit and the disclaimer are the two lines a reader most needs. They sit inside a welcome message, where they read as courtesy.
  • No version, no date, no approval trail. A manual with safety content needs all three, and a printed copy on the floor needs them most.
  • No statement of who owns factual accuracy. That line protects the client and the writer, and it is missing.

Written output

About this manual

Who this manual is for

Technicians who hold a current site induction and who operate or maintain the machines listed in section 1. Trainees use the operator workbook.

What you can do after using it

Set a machine up, run it through a shift, shut it down, and record what you did.

How to read it

Read sections 1 to 4 in order before you work on a machine alone. Sections 5 to 11 are reference material. Use them as needed.

Conventions

  • WARNING: Risk of injury or death. Read before you perform the step.
  • CAUTION: Risk of equipment damage.
  • NOTE: Additional information.
  • [Bold text] marks a term defined in the glossary.

Scope

This manual describes machine operation, routine maintenance, and shift handover only. Where this manual and the site safety rules differ, follow the site safety rules.

Accuracy and approval

Technical content and safety statements are approved by the maintenance engineer named in the approval record. Structure, terminology, and clarity are the writer’s responsibility.

Version

Version 1.0. Issued [date]. Approved by [name]. Check the version before you use a printed copy.

What changed

A welcome note became a working front page. It tells a technician in four lines whether this manual is theirs. It names a version, an approver, and which rule wins when two rules disagree.

Technical documentation

“Support takes the same call every week”

Technical procedure

The cost: Support cost scales with sales.

Source takes like 4 min but people panic at 2 min and unplug it
Written 7. Wait for the LED to turn green. The update takes up to 5 minutes.

“Support takes the same call every week”

Technical procedure
Constructed demonstration

The source is fictional; the method is the one I use.

Raw source · engineer’s chat reply, pasted into a ticket

yeah so they just need to update the firmware, download the pkg from the portal (the 2.x one not 1.9, 1.9 is still up there for the old units) put it on a USB stick formatted FAT32, plug it in, hold the mode button while powering on. LED goes amber then green. if it goes red they pulled the stick too early, tell them to just redo it. takes like 4 min but people panic at 2 min and unplug it. don't do it under 20% battery obviously

What I found

  • Two package versions on the portal with no way to tell which unit takes which. This is the single most likely failure and it is written as a parenthesis.
  • A destructive failure mode (“they pulled the stick too early”) documented only as a support workaround. It belongs in the procedure as a caution with its consequence.
  • A known human failure (“people panic at 2 min”) is a documentation gap, not a user error. The procedure must state the expected duration before the wait begins.
  • LED states carry all the feedback in this task and appear inline, unlabelled. Three states means a status table.
  • The battery prerequisite arrives last, after the reader has already started.

Written output

Firmware update, series 2 units

Purpose

Install firmware 2.x on a series 2 unit from a USB drive.

Before you begin

  1. Confirm that the unit is a series 2 model. Check the label on the base. Series 1 units require the 1.9 package and a different procedure.
  2. Confirm that the battery is above 20%.
  3. Format a USB drive as FAT32.

CAUTION: Do not remove the USB drive or cut power during the update. An interrupted update leaves the unit unable to start.

Procedure

  1. Download the 2.x firmware package from the support portal.
  2. Copy the package to the root folder of the USB drive.
  3. Switch off the unit.
  4. Insert the USB drive.
  5. Hold the mode button, then switch on the unit.
  6. Release the mode button when the LED turns amber.
  7. Wait for the LED to turn green. The update takes up to 5 minutes.
  8. Remove the USB drive.
  9. Switch the unit off, then on.

LED states

LEDMeaningAction
AmberUpdate in progressWait. Do not remove the drive.
GreenUpdate completeContinue to step 8.
RedUpdate failedRepeat the procedure from step 3.

Troubleshooting

  • LED stays off at step 5: Confirm the drive is FAT32. Confirm the package is in the root folder, not in a subfolder.
What changed

The version trap moved to step 1 of the prerequisites. The five-minute wait got written down, so the reader stops unplugging the unit at two minutes.

Choose the document by the problem

The document type is a decision, not a preference. Using the wrong one is why a manual gets written and then ignored.

People perform one task differently

Someone needs to complete one task correctly

Procedure

New staff need to learn a skill

People keep searching for the same answer

The whole operation needs one controlled source

From expert knowledge to approved documentation

Seven steps. Two of them are shown below with the work they produce.

01

Capture. Interview, transcript, demonstration, notes, existing documents.

02

Diagnose. Find missing prerequisites, sequence gaps, undefined terms, contradictions, and safety questions.

03

Structure. Choose the document type and information architecture.

04

Draft. Convert the source into executable instructions.

05

Verify. Return technical, practice, and safety questions to the SME.

06

Test. Check whether a reader can perform the task without hidden knowledge.

07

Approve. Record owner, version, approver, and issue date.

Steps 01 and 05, on the sample above

Writer

What tells you the tension is right?

Technician

I push it with my thumb. After twenty years you feel it.

Writer

A technician in their first week has no twenty years. What can they measure instead?

Technician

Deflection. Push the middle of the span and see how far it drops.

Writer

How far should it drop, and with how much push?

Technician

A millimetre and a half per hundred of centre distance. Twenty newtons on the gauge.

Writer

What do they do when it drops further than that?

Technician

Slacken the four motor foot bolts, pull the motor back, tighten up, measure again.

What the exchange produced

Acceptance criterion

Deflection measures 1.5 mm for each 100 mm of centre distance under 20 N. SME verify

Corrective sequence, procedure ADJ-04

  1. Loosen the four motor foot bolts.
  2. Move the motor away from the driven pulley until the deflection reaches the acceptance criterion.
  3. Tighten the four motor foot bolts to the torque on the machine data sheet.
  4. Measure the deflection again.

Who owns what

The expert approves
  • Technical accuracy
  • Safety claims
  • Limits and exceptions
  • Permitted variations
  • The final procedure
I own
  • Information architecture
  • Sequencing
  • Terminology
  • Procedural clarity
  • Document consistency
  • Version structure
Anything uncertain SME verify

What makes an instruction usable

Action
  • One instruction per sentence
  • Use imperative verbs
  • Put steps in execution order
Language
  • One term for one concept
  • Avoid unnecessary noun clusters
  • Keep procedural sentences short
Safety
  • Put warnings before the related action
  • State the consequence
  • Flag unverified safety claims
Structure
  • Use lists for sequences
  • Separate prerequisites from instructions
  • Keep exceptions close to the affected step

My procedural writing approach is informed by ASD-STE100 principles: Controlled terminology, short instructions, explicit sequencing, and warnings before the action they protect.

I do not need to be the subject expert

The subject changes every time. The job stays the same: Find what the source leaves out, then build the structure that answers it.

What a source leaves out is predictable, and it changes with the kind of document rather than with the subject.

Software

Typically missing

State, failure condition, expected result.

Operations

Typically missing

Owner, timing, exception, handoff.

Training

Typically missing

Outcome, sequence, assessment.

Physical procedure

Typically missing

Prerequisite, tool specification, safety boundary, observable result.

Selected work

The documentation and knowledge-operations work behind this service, written up in full.

AI-Assisted Documentation Pipeline Long, fragmented source material becomes structured, review-ready documentation. Knowledge Article Staging Tool A browser-based converter turns Word drafts into clean, validated, publish-ready HTML. Knowledge Lifecycle & Governance Framework Nine lifecycle statuses, ownership, evidence rules, and review commitments as one controlled model.
View all case studies