“What is written” and “being able to act” are different things

Sometimes, even when you explain something, it just doesn't get across.

I made the materials. I wrote down the procedures. I included the necessary information. It should have been perfect, yet the other person still comes back with questions. Or the work stops halfway through.

For example, have you ever had an experience like this?

“In which environment should I execute this?”
“What should I look at to determine if it finished successfully?”
“If this error appears, should I continue?”

From the writer's perspective, I thought I had explained those parts too. But for the reader, their decision-making stops right there. When you create materials or procedure manuals for work, this gap happens quite often.

At first, I would think, “Was my explanation poor?” or “Do I need to write better sentences?” Of course, I wouldn't say that speaking style or writing ability have nothing to do with it. But recently, I've come to think that the problem lies a bit further back.

Explaining is not about speaking well yourself. It is about creating a state where the other person can understand.
This way of thinking has stayed with me ever since.

“What is written” and “being able to act” are different things

There are times when the content of a procedure manual is correct, but the reader cannot act on it.

The work content is written down. The commands are there. The logs to check are also written. But for someone doing the task for the first time, that alone is sometimes not enough.

Why are we doing this task? What should be checked before starting? What state can be considered normal? If an unexpected display appears, should I continue or stop? Where should I stop making my own judgments and ask for confirmation?

These things that seem like “you should know this” have become common sense for the writer. The longer your experience, the easier it is for that common sense to slip out of the procedure manual. This surfaces when handing over work to younger staff or other teams.

I have also had the experience where, even though I thought I had written the procedure correctly, the worker asked me, “How far should I proceed before I can judge it as complete?” I had written down the screens and logs to check. But that was still not enough as “material to judge whether it is normal or not.”

When I receive feedback during a review or get questions back, at first I think, “But I wrote it properly.” However, when I look back at it later, the material for the reader to make a judgment is missing. After having that experience several times, I came to think that explanation is not just about the beauty of the sentences.

It is not that the other person doesn't understand; it is that we are not looking at the other person's prerequisites. I believe we need to start by organizing from there.

Organize in the order of trunk, branches, and leaves

When organizing this problem, the order of “trunk, branches, and leaves” is helpful.

The trunk is the goal and purpose of what the topic is about. The branches are the overall flow of what perspectives exist. The leaves are the specific operational procedures and supplementary information.

If this order is reversed, the reader is shown only the leaves and cannot understand the shape of the tree. A state where detailed procedures are lined up but the overall picture cannot be grasped is a common cause for stopping the reader. Even if it looks polite at first glance, it is not kind to the reader.

When I look back at my own materials and procedure manuals, I find that I often skip this. Am I starting with the detailed work right away? Is “what this work is for” placed at the beginning? Just by being conscious of that, the way it is conveyed changes.

There are many shortcomings in procedure manuals that only become apparent after they are actually used. By fixing the parts where questions arise or where work comes to a halt, the document gradually becomes more usable.

It is more about the design of the sequence and prerequisites than writing ability.

There are times when you want to say, "I explained it" or "It is written in the document." However, that alone does not necessarily mean the other person is in a position to act.

Does the other person know what to do next? When they get stuck, do they have the information needed to make a decision? I think only when you look at those aspects can you say that an explanation is truly functional.

The next time I create a procedure manual or document, I want to review it not just for whether it is "written properly," but for whether the other person can proceed without stopping. I feel that my approach to explanation will change a little from there.

Related Articles/Magazines

I am writing little by little about how to connect the books I read to my work and life.

My book reviews and articles on verbalizing thoughts are collected here.
https://note.com/komugi_0121/m/m8b60f87451b5