Clarity Arrives Just in Time (#26)

The Discipline of Restraint in Technical Writing

When we’re writing documentation for our clients, we often have to reference third-party enterprise docs. We’ll ask an AI tool to surface the relevant pages, then we skim the snippets, click through, and verify what’s actually there.

Too often, that verification feels like wading into a bureaucratic swamp. The cursor blinks. The headers sprawl. Somewhere inside the paragraph, I’m supposed to find the thing I came for, but first, there’s a lecture.

A wall of context rises in front of me:

• A verbose introduction that gestures toward value but never lands on it

• A dense list of “considerations,” where every bullet hedges against the last

• Steps that multiply before my eyes, each containing three more steps nested inside

• Sentences that start as guidance and end as philosophy or apology or both

By the second scroll, I’ve forgotten what I was even trying to confirm.

By the third, I’m not sure if I’m still the target audience or an accidental auditor.

If you felt your attention drift just now, that’s the point.

Sometimes I joke that I need a continuing-education Certificate in Enterprise-Documentation Comprehension.

I know smart people have written these articles: engineers, product managers. They understand exactly how everything fits together.

And that’s the problem. When you understand everything, you forget what it feels like to understand nothing. You write down everything you know, exhaustively. But there is a cost to that kind of completeness.

---

The Cost of Completeness

Enterprise documentation often tries to educate before it orients. It explains every variable, dependency, and exception before the user has taken the first action.

The result is not comprehension. It is cognitive overload.

When users encounter more detail than their current goal requires, they begin to lose track of relevance. Each paragraph competes for attention, and the effort of deciding what to ignore becomes its own form of confusion.

Research supports this. A 2024 scoping review on information overload found that excessive detail and low-relevance information increase cognitive strain, slow comprehension, and degrade decision quality. Enterprise documentation often mistakes completeness for clarity. What begins as a gesture of thoroughness becomes a barrier to understanding.

The irony is that this overload rarely comes from neglect. It comes from mastery, from people who know too much and care too deeply.

---

When Experts Confuse Mastery with Mercy

Product managers and engineers write the way they think. They trace dependencies, qualify exceptions, and defend completeness. Their instincts are architectural, not narrative. They see the entire system at once and assume that understanding the whole will make every part clearer.

They want to protect users from confusion, so they explain everything that might ever go wrong. They want to be transparent, responsible, and helpful. They want to prove they have considered every path the user could take. In their eyes, this is mercy.

Inside many organizations, completeness is rewarded. A missing note about a configuration flag or an unmentioned permission setting can trigger another meeting or a support escalation. The unspoken lesson is clear: cover every scenario, or risk being blamed for what you left out.

Over time, experts begin to protect themselves as much as their users. Every sentence becomes a small act of self-defense. In an expert’s mind, if something breaks, at least the documentation mentioned it somewhere.

The result isn’t documentation that protects users. It buries them instead, overwhelming action and eroding the very clarity it meant to provide.

---

Discipline of Timing

So if the goal is to guide users toward finishing a task, then every decision in your writing should serve that end. The work is about sequencing knowledge so it arrives exactly when it is needed.

In UX design, this principle is called progressive disclosure: revealing only what is needed the moment the user needs it. In ancient rhetoric, the Greeks called it kairos, the right word at the right time. For us as writers, think of it as just-in-time guidance.

Our job is to pace revelation. We lose users when we try to prepare them for every possibility instead of guiding them along the most direct path to success, no matter how complex the task may be.

At any given moment, a user needs three things:

1. What to do

2. Why it matters right now

3. What they should see next if it worked

That’s it.

Everything else belongs behind a link, in a callout, or in an FAQ.

Think about it. Does Google Maps explain the theory of traffic flow? No. It just tells you to turn at the next traffic light.

---

Practical Application

So, what does this look like in end-user documentation?

Below are two examples: one written for developers and one for a general product interface. Both follow the same pattern. They tell the reader exactly what to do, why it matters in that moment, and what to expect once it’s done.

Example 1: Code-based workflow

Follow these steps to retrieve SSAI session data:

1. In your player configuration, add an event listener for sessiondata:
   
   At runtime, the player parses the manifest for #EXT-X-SESSION-DATA and emits a sessiondata event when it detects the com.example.session-endpoint.

   player.addEventListener(’sesiondata’, (data) => {
     if (data.id === ‘com.example.session-endpoint’) {
       logMessage(`session info URL: ${data.uri}`);
       fetchInfoJson(data.uri);
     }
   });

2. When sessiondata fires during playback, fetch the session data. The endpoint will return a JSON representation of the ad breaks in the session.

Each step identifies a clear action, explains its purpose at that moment, and describes what to expect immediately afterward. The code block demonstrates the behavior, and the supporting text gives just enough context to stay oriented.

Example 2: Interface-based workflow

Follow the steps to create a new property:

1. On the Properties tab, click Create property. The Create property panel appears.

2. Enter a Property name.

3. (Optional for users with DRM entitlement) Toggle Digital Rights Management to ON.

ℹ Learn more about DRM-enabled properties.

4. Click Save.

The instructions are sequential and self-contained. Each step tells the user what to do and what they will see or achieve next. The DRM-enabled properties information is relevant but not essential, so it sits in a callout box that can be read or ignored without breaking flow.

The result is clear, scannable guidance that lets the reader act before fatigue sets in.

---

Clarity Arrives Just in Time

Good documentation is not an archive of every nuance of a product. It is a guide that gives readers only what they need, when they need it.

Every sentence should serve the user’s momentum. More information may feel safer inside a team or earn quiet approval during review, but it often derails users. What feels responsible inside an organization often feels exhausting outside of it.

Remember, users need only three things:

• What to do

• Why it matters right now

• What to expect next

Everything else can wait.

Good documentation ends where the user completes the intended task.