There’s a moment in most documentation jobs where an engineer explains something clearly, completely, in a way that makes total sense.
You take notes, you thank them, you go to write it up.
Then halfway through the third step you stop.
What happens if the user doesn’t have that permission?
Nothing in the notes covers it, because nobody thought to mention it.
That noticing is the job.
Not the writing, the noticing.
🔍 Why gaps are invisible to the person who knows
Engineers don’t withhold information, they just can’t see what’s obvious to them.
Someone who’s worked on a system for 4 years has internalised a hundred small facts.
Which fields populate automatically.
What the error means when it appears.
Why nobody uses that menu option anymore.
They don’t mention any of it, because to them it isn’t information, it’s just how the thing is.
A writer sitting slightly outside the system is well placed to catch that.
You’re close enough to follow the explanation, far enough to notice when a step doesn’t quite connect to the next one.
That gap between what was said, what a reader would need, is where most documentation value sits.
❓ The questions that surface missing information
Some questions consistently pull out what wasn’t volunteered.
- What happens if that field is empty?
- Who has permission to do this, who doesn’t?
- What does the user see if it fails?
- Is that always true, or usually true?
- What would someone do if the person who normally handles this is away?
- Has anyone ever done this wrong, what happened?
That last one is unusually productive.
People remember failures vividly, so asking about them gets you the edge cases that a normal walkthrough skips entirely.
Another useful move.
When an answer comes back thin, repeat the last few words as a question, then wait.
“It just goes through automatically.”
“Automatically?”
Then say nothing.
Most people fill the silence with the exception you needed.
⚠️ What writers are good at spotting
Beyond missing information, there’s a category of problem that shows up when you try to write something down clearly.
Ambiguity survives conversation easily, though it can’t survive a numbered procedure.
The things that regularly surface.
Ambiguity.
“Approved by management” means the team leader in one department, the general manager in another.
Writing it down forces someone to decide which.
Inconsistency.
Three documents use 3 terms for the same object.
The system uses a fourth.
Nobody noticed until someone had to write a glossary.
Edge cases.
The process assumes 1 attachment, though people regularly upload 14.
The process assumes the requester is an employee, though contractors use it too.
Risk.
A step that deletes something with no confirmation.
An approval that can be bypassed if you know the direct URL.
A manual workaround that only 1 person knows how to do.
That last one is worth flagging to the program, not just documenting.
A process depending on a single person is a risk register item, discovered through documentation work.
🗣️ Raising it without being difficult
Finding problems is easy, raising them well takes a bit more care.
An engineer who’s just spent 40 minutes explaining something doesn’t want to hear that it’s flawed.
A few things that keep it collaborative.
- Ask rather than assert, since “what happens if” lands better than “this won’t work”
- Frame it as your confusion, not their error
- Bring it up while there’s still time to change something
- Note the fix, not just the problem
- Say plainly when it’s a small thing you’re just noting for completeness
Most engineers respond well to genuine curiosity about how the system behaves.
They respond poorly to feeling audited.
Same information, different reception, entirely down to how it’s asked.
✅ Why this can’t be automated away
A tool can produce a fluent procedure from a transcript.
What it can’t do is notice that the transcript never mentioned permissions, because it doesn’t know a reader would need that.
It can’t tell that “approved by management” is ambiguous within this particular organisation.
It can’t recognise that a step depending on 1 person is a business continuity risk.
Those require knowing what a reader needs, what tends to go wrong, what questions the material hasn’t answered yet.
That’s experience.
Writing the procedure is the easy part.
Knowing what the procedure is missing is what people are actually paying for.
About the author
Aiver is the managing consultant at Aliso Digital, an IT consultancy based in Melbourne.
For 19 years he’s worked on enterprise digital transformation programs.
His experience spans ITSM, HRIS, ERP, CRM, POS, KMS and EDRMS platforms, plus workflow automation.
His work covers business analysis, process optimisation, technical writing, knowledge management and UI / UX design.
He has worked across government, healthcare, science and medical research, finance, education, telecommunications, infrastructure, aviation, construction and property, technology, retail, logistics, pharmacy, insurance and professional services.
He has worked on multi-million dollar programs running years at a time, for national organisations and global firms, reaching millions of end users.
He has run his own consultancy for 12 years and works with a small number of clients at a time.
Available for remote and hybrid contracts.
alisodigital.com
