Everyone can be right.

And the product can still be lying. The interface suggests one thing. The system does another. And the output gives the user just enough confidence to believe a promise was honored.

A field says: Add additional instructions. The user adds additional instructions. The output looks aligned.

The team moves on.

No one asks:

Did the system honor the contract it made with the user?

And increasingly, that’s the question technical writers are left to answer.

The Contract Behind the Interface

A software product is full of promises.

Some are explicit. A button says Delete. A field says Additional information. A toggle says Enable. A status says Synced.

Some are implied. If a user enters instructions into a field, the user assumes those instructions influence the result. If a workflow can be configured, the user assumes the configuration changes behavior. If an AI tool invites specificity, the user assumes specificity matters.

Each assumption is a contract.

A feature begins as a clean use case. The PM frames the value. The designer builds the flow. The executive sees the demo and approves it. Engineering implements the defined behavior. QA validates the expected path.

Everything checks out. Yet the contract hasn’t been validated.

The team validated the happy path—a controlled scenario where the feature works.The happy path is not fake. It’s just incomplete.

It is, in many ways, a sales artifact.

It shows the product working under ideal conditions, with aligned assumptions, clean inputs, and cooperative behavior.

Users do not operate under ideal conditions. They arrive with partial knowledge, messy data, and vague intent.

They click things in the wrong order.
They over-specify.
They under-specify.
They assume the product does what it says.

And this is the moment the contract is tested.

Because the user does not experience the product in layers. They experience it as one continuous claim.

They do not care that:

• the frontend passed the value.

• the backend accepted the request.

• the model returned something plausible.

They care that the thing they were led to expect did not happen.

That gap—between claimed behavior and lived behavior—is where the contract breaks.

And it is precisely the gap most teams are not structured to see.

The Assembly Line Came for Product Teams

This problem is not new. It is just wearing better software.

Modern software-as-a-service (SaaS) development follows the logic of industrial specialization. Work is broken into discrete parts. Ownership is assigned. Tasks move across the line. Each person contributes to a piece of the whole without necessarily holding the whole in view.

The assembly line made production efficient. It also created a durable instinct: divide the labor, optimize the part, increase throughput.

In the SaaS world, a feature moves from idea to design to implementation to validation. By the end, it has passed through enough specialized hands that no one is responsible for the behavior of the system as a whole.

This division of labor is necessary. Complex products require depth, focus, and clear boundaries.

But every system optimized for specialization creates a predictable blind spot: what happens between the parts.

That is where the user lives.

The user does not experience the product in layers. They experience the transitions, the seams, the places where assumptions meet reality.

And most teams are too busy polishing their layers to inspect those seams.

The AI Field That May Not Have Mattered

I was documenting an AI content generation feature.

In the UI, under the Prompt section, there was a field labeled Additional information. The assumption was obvious: whatever I entered there should influence the generated output.

So I tested the field to understand it well enough to explain it.

I started with a detailed prompt—tone, structure, length, style. Clear, optimistic, educational. Strong hook. Clean progression. Conversational delivery.

The output came back.

Then I simplified the additional information. Stripped it down. Different tone. Different structure.

The output came back again.

There wasn’t a meaningful difference.

Not broken.

Off.

That distinction matters.

Because “off” is easy to dismiss. It’s not a loud failure. It’s something you can explain away—model variance, prompt sensitivity, expected behavior, “AI being AI.”

But I’ve learned to pay attention to off.

So I asked the engineer: what kind of prompt is this field actually expecting?

He walked me through how the system was structured—what it was already doing by default. My input looked like it was working because it already aligned with that behavior.

But it didn’t explain why changing the prompt had no effect on the output.

So he checked the code.

And that’s when it became clear: the Additional information field wasn’t being passed into the generation logic at all.

The UI field accepted input.
The code didn’t pass it into the logic.

That’s the work.

Not just polishing language.
Not just shipping a help article.

I was testing whether the system honored its own contract.

The UI said it mattered.

The code proved it didn’t.

Tooling Makes the Blind Spot Worse

The rise of AI-assisted development has intensified this problem.

Not because the tools are ineffective. They are clearly useful. Research from GitHub shows that Copilot-assisted code can improve functional correctness, readability, and maintainability in controlled conditions.

The issue is not whether AI helps engineers ship.

It does.

The issue is what happens when faster shipping becomes a substitute for fuller verification.

Modern development is saturated with signals of correctness.

A unit test validates a unit. An integration test validates a defined interaction. A model evaluation checks selected outputs. A dashboard confirms the system did something measurable.

All of it builds confidence—within scope.

None of it answers the broader question:

Does the product behave the way the user believes it does?

That question is too cross-functional for a test case and too interpretive for most tools.

Traditional software fails in binary ways: a setting saves or it doesn’t.

AI systems fail differently. They may partially honor a request—or ignore it entirely while producing something plausible enough to pass a casual review.

That’s the trap.

The output looks right. The system appears to be working. The signals all align.

But nothing proves the system actually listened.

Teams mistake coincidence for causality.

This is the new failure mode: plausible success masking actual neglect. A plausible output lets the team move on while the system quietly ignores the user.

When the Question Changes

Technical writers do not replace formal evaluation, QA, or engineering validation. But we often perform a kind of qualitative trust check that those signals miss.

In addition to “how do I explain this?”, we have to ask “is this true?”

That question doesn’t get answered abstractly. It gets answered by working the system—by following the friction, pressing on the gaps, and forcing the behavior to reveal itself.

That work isn’t random.

In practice, it looks like this:

1. Identify — You spot the misalignment. The system produces an outcome that doesn’t match what the interface or workflow implies.

2. Hypothesize — You turn “this feels off” into a testable suspicion about how the system is actually behaving.

3. Interrogate — You apply pressure. You trace the input, vary conditions, and ask what actually influences the outcome.

4. Isolate — You separate signal from noise. You determine how the system actually behaves—whether incomplete, scoped, or misaligned with the interface.

5. Correct — You force alignment. You work with the team to ensure the UI reflects the behavior, the behavior matches the contract, and the documentation describes it without caveat.

This is how you close the gap between what the system says and what it does.

Outside the Layers

Teams build in parts. Each person focuses on a scoped layer. The component renders. The endpoint responds. The test passes. From inside those layers, everything looks correct.

But the product isn’t experienced in layers.

The work requires stepping outside that view. That’s where the technical writer operates. To explain the system honestly, you have to move through the entire workflow—start where the user starts, follow what they see, and decide whether it holds together.

You’re the first one trying to describe the system as a single, coherent experience.

And when it doesn’t hold together, you don’t get to ignore it.

At that point, the work isn’t describing the product.

It’s making sure the product, end to end, does what it says it does.

I’m taking an online class at an Ivy League university. It’s part of a graduate program I decided to undertake to prove something to myself. And, I think I’ve found something different than I sought: Truth doesn’t belong to anyone.

But it belongs to all of us.

Let me explain.

A Tale of Two Brothers

When we graduated high school, my best friend and I parted ways. He went to Harvard to study economics, and I went to a small Christian school in Texas to run track and study the Bible. He found a home in prestigious Cambridge, and I chased around tumbleweeds in the Wild West.

Secretly, I resented the split in our paths — not because I didn’t want my friend to succeed at an acclaimed university, but because I doubted my ability to succeed in the same way. I wondered if I could do it, too. And I was terrified that I couldn’t.

As time went on, it became obvious that my friend made the right decision for himself. He won a plethora of academic awards and became deeply involved in the Harvard community, which connected him to unique (and lucrative) professional opportunities post-graduation. I was happy for him.

However, clarity never came that I had made the right decision for myself. In fact, things got hard. My life during and after college was difficult, fraught with relational and financial struggles. I reconsidered my path many times and felt deeply insecure that I had made a wrong choice somewhere along the line.

So, in the fall of 2024, I decided to do it. I applied to and enrolled in a graduate program at an Ivy League. I wanted to know whether I could do what my friend had done, but more importantly, whether I had chosen the right path.

Almost two years have passed. In that time, I’ve written research papers, taken midterms, and collaborated with peers on all kinds of projects. And I’ve succeeded. To date, I’ve maintained a high GPA and earned the respect of my teachers.

But the experience hasn’t been what I thought it would be.

Waking Up

To be clear, my colleagues and professors are wonderful people. Indeed, many of them are experts in their fields and have stories that deserve to be told. I deeply respect them.

Even still, when I entered class for the first time two years ago, I reckoned I would receive some kind of theophany. I fully expected the clouds to split, light to shine down from the heavens, and the voice of God to announce the secrets of existence to us, such divine inspiration being reserved only for those seated in the East coast’s greatest institutions.

Instead, I saw the disembodied faces of a dozen people pop up on Zoom, and a man who looked like my neighbor announced the syllabus.

Yes – we had excellent conversations in that class, but it wasn’t because of the institution, per se. It was because of the people who had joined it, willing to discuss openly and critically.

I’ve relived this experience over several semesters now:

• Expecting divine knowledge

• Receiving human information

• Sharing human conversations

It’s like I’ve been caught in some kind of karmic cycle. Every few months I’m reborn into the idea that “something else” lies just beyond me.

As it turns out, the “something else” has never been beyond me at all.

Reevaluating

My relative success in the Ivy League has been the proof I initially sought: I am, in fact, able to walk that path.

However, the humanity of the Ivy League has been the proof that I really needed: My decision to walk a different path out of high school was not wasted.

Humanity is the answer.

There is no secret arbiter of truth in this world. Information is a collective resource that we excavate together. In every field – technology, science, philosophy, the arts – we participate in an ongoing conversation that has echoed through generations of humans who asked questions like us.

No doubt, there are minds who are uniquely gifted. But even the Einsteins of the world exist within a community, and it’s that community which gives our Einsteins a society to change.

In other words, whether we live in Cambridge, Texas, or anywhere else, we’re all people.

Humanity and Writing

I know. At this point, you must be gawking at the lack of my prophetic insight.

“Wow, Gabe. This is really not deep stuff. People are just people. So what?”

This realization is transforming my personal epistemology.

In an academic context, I once expected truth only to come from some impossibly educated, credentialed demi-god who lives in the library’s special collection. What I found were normal people who were passionate about a subject and tried to teach it. They didn’t know everything, and they didn’t always explain it well. But they cared, and that was enough.

In a professional context, I once expected truth only to come from a product manager who knew all the technical specs of her project, the value it offered in the market, and its future vision. What I found were regular humans being pulled in different directions, learning on-the-job, and failing quite often.

In fact, the volume of mistakes actually terrified me at first, until it freed me. I was allowed to be human, to try, and to fail like everyone else. And most importantly, I was allowed to care.

Epistemologically, this tells me that truth has more to do with pursuit than perfection. As technical writers, we are juggling docs for products that are continually evolving. For most of us, there is no way to stay on top of everything.

We aren’t “perfect” writers, locked away in solitary chambers void of distraction or confusion. We’re on the ground in organizations that don’t have their shit together, and as a result, we probably don’t either!

In these situations, our humanness is actually our greatest asset. Our ability to care about the process allows us to convey truth to those who want it.

When we care to ask questions, explore the feature, and consider its ramifications, we do the same work as Harvard scholars. We exercise our humanness to piece together the truth, which is still being revealed to us.

Truth is not a perfect pursuit. It is messy, variable, and fluctuating. But it can be a pursuit of love.

Bringing It Together

Class has ended since I started writing this piece. My professor never really did win my attention tonight, and that’s okay. He’s a person, after all.

Now, at the risk of losing your attention, I’ll pull things together.

No one has a monopoly on truth. It doesn’t belong to professors, nor to product managers, nor to engineers. It’s something that emerges when all of us come together and figure it out. This is partly why the truth is beautiful — because it involves all of us.

So, the next time you write a doc, I hope you can strip yourself of the illusion that the answer to your question is somewhere else. Between you and the people around you, I believe you can find it.

Subscribe now

Share

So you must pass them by.

Seal your crew’s ears with wax so they cannot hear. But if you want to listen, you must be bound. Hands and feet. Tied to the mast so you cannot move. Because when the song takes hold—and it will—you will beg to be released.

Your crew must not listen. They must tie you tighter.” This is Circe’s paraphrased warning to Odysseus.

He is saved because the warning didn’t just describe the danger. It told him what to do before it began.

A lot of documentation does not treat warnings this way.

We believe that once a risk is named, it has been handled. Add a warning. Add a note. The danger is now visible, acknowledged, and contained.

But a warning can be accurate. Visible. It can be approved by everyone in the room.

And once the user is committed and in motion, the warning can still fail.

More than informing

Well-written processes don’t just explain. They create sequence, pace, and progress:

1. Do this.

2. Complete this.

3. Continue.

Each step builds confidence in the next.

Once a reader is moving through a procedure, he is no longer evaluating each step from scratch. He is following. Completing. Advancing. The document has already told him: keep going.

This is where warnings begin to lose.

A callout is present. The risk is named. The sentence may even be precise.

But the reader keeps going.

Because the document is doing more than informing.

It is creating momentum.

And once you see that, you start to notice it everywhere.

You see it in admin documentation that calmly walks users through destructive changes and adds a soft note about downstream effects.

You see it in setup guides that frame invasive defaults as standard configuration, with a brief disclosure that additional data may be collected.

You see it in troubleshooting flows that treat preventable damage like routine cleanup: if something breaks, here is how to restore it.

You see it in workplace documentation that teaches teams how to execute a process efficiently while burying the human cost in a caveat, disclaimer, or final-note section.

And you see it in AI guidance that warns users not to rely too heavily on generated output while still building the whole experience around speed, trust, and output volume.

The pattern is the same.

The warning is there. The momentum is elsewhere.

If momentum is driving this, why not write stronger warnings? Why do weak warnings persist?

Why Weak Warnings Persist

Weak warnings rarely come from a single bad decision or a careless writer.

They tend to emerge from environments where multiple pressures are quietly aligned.

A risk is identified. It needs to be acknowledged. So a warning is added. And in many cases, a weak warning is enough to satisfy requirements:

• Pass legal review

• Provide language that can be pointed to later

• Signal that the risk was considered

• Create a record that the user was informed

A warning can acknowledge a risk without altering the path that leads to it. The workflow stays intact. The default remains untouched. The user is still guided forward.

It allows teams to address a known problem without slowing the path to completion. It provides cover by giving language that can be referenced later by support, legal, or the team itself.

In other words, weak warnings persist because they allow teams to acknowledge risk without accepting responsibility for preventing it.

The product or workflow does not need to change.

And in many environments, that is exactly the point.

Change the Outcome

Warnings fall into one of three categories:

• Warnings that perform responsibility. They acknowledge the risk so the team can say it was covered

• Warnings that trail behind. They mention the risk, but only after the user is already committed

• Warnings that interrupt. They change what the user does before the risk occurs

A strong warning interrupts at the moment of commitment and changes the decision. A strong warning conveys three things:

• The concern

• Potential repercussions

• An avoidance strategy

You can see the difference in how the same situation is written

• Perform Responsibility: This step may impact existing configurations.

• Trail Behind: This step overwrites existing settings. Consider exporting your configuration if needed.

• Interruption: Before continuing, export your current configuration. The next step overwrites existing settings and cannot be undone.

That is the difference between acknowledging a risk and guiding away from negative outcomes.

Or It Does Nothing

Circe’s warning did not merely acknowledge danger. It interrupted the path toward the danger.

Most documentation warnings do not. They preserve the workflow, satisfy the obligation, and keep the user moving toward the consequence.

At that point, the warning is no longer a protection.

It is theater.

He was not just another contender. He was the champion. For eleven years (1912-1923), he held the World Featherweight title. No one in the division had ever held it longer, and no one since has repeated the feat. Kilbane was disciplined, elusive, and patient. He was known less for brute force and more for tactical control in managing a fight.

But that night in New York, he faced the Frenchman Eugène Criqui.

By the sixth round, it was over.

Criqui landed a right hook to the jaw that dropped Kilbane hard. The referee counted, and the title slipped away to a new victor. Kilbane’s history reign ended in a single exchange.

For many, Kilbane’s defeat is an appropriate salute to his career — like a warrior who proudly dies in battle. But for others, a question lingered around that fight. Not whether Kilbane was a great boxer. That was already settled. The question was quieter: Should Kilbane have taken the fight at all?

I’ve found myself mulling over this recently, because as it happens, Kilbane was my grandfather’s uncle.

Courtesy of the Cleveland State University Library Special Collection

The Review That Changed the Document

Recently, I wrote a dense, technical article for a client in ad tech. I wrote something I thought was effective and clear to the end user, so I submitted it for review expecting a quick win and publish.

Much to my surprise, the client responded with dozens of suggested edits. By the end, I was looking at an entirely different article. And I did not like it.

I genuinely believed that my initial version of the document was better. Its wording was clearer and its layout removed friction for the reader. The version the product manager recommended introduced a complex structure, with level 4 and 5 headers that risked burying information too deep in the page to ever be found.

But I hit publish anyway.

I decided not to enter the ring and fight.

When the Fight Is the Problem

Kilbane did not lose because he forgot how to box. He lost because he stepped into a fight he did not need to take.

He had already done the work. Eleven years as champion had secured his legacy. Then, after a two-and-a-half year retirement, he came back to defend a title he did not have to risk. And in that decision, he exposed himself to a fight that carried consequences greater than the moment required.

Time away matters. The body changes and instinct dulls. The rhythm of the ring is not something you store and retrieve at will, but something you must live inside. Kilbane could still throw a punch, but he was no longer living in that rhythm.

So the mistake was not technical. It was the decision to enter the ring at all.

Technical writers make a similar mistake all the time.

We assume every piece of feedback is a fight worth taking. We treat each edit as a moment to defend clarity, structure, or craft. We step into debates over header levels, phrasing, and layout as if the title is on the line.

But it is not.

Not every comment deserves resistance. Not every disagreement needs to be resolved. When the core information is intact and the user can still succeed, the fight is often unnecessary.

And yet we step in anyway.

We argue over structure when the workflow still works. We spend time and energy protecting details that do not meaningfully affect the reader.

In doing so, we create risk where none existed. We turn a stable document into a contested space. We trade progress for control.

Some fights in documentation are real. They protect the user or somehow mitigate failure, clarifying what would otherwise break.

But many fights are not real.

And if you step into all of them, eventually, like Kilbane, you will find yourself in a fight you did not need to take, risking something far more valuable than the point you were trying to win.

Naming the Fights

To choose a fight wisely, we need to understand what kind of fight we’re actually in.

Clarity is the ability of a reader to understand and act without hesitation.

Alignment is the agreement between the document and the organization that stands behind it.

Authority is the subtle question behind every edit. Who gets the final word?

These forces are always present, and often, they pull in different directions. The problem is not that they conflict. The problem is that we fail to recognize which one is driving the moment in front of us.

And when we misread that, we pick the wrong battles.

We argue for clarity when the real issue is authority. We push for structure when the organization is signaling alignment. We defend our craft when the document no longer belongs fully to us.

But once you can name the force, the decision becomes clearer.

If clarity is at risk, you step in. If alignment is the priority, you may need to yield. If authority is being asserted, you decide whether the point is worth pressing.

This is what it means to pick the right fight. It’s not about winning every exchange, but recognizing which kind of fight you are in before you decide to engage.

The Fights You Let Go

I realized something in that review cycle. My expectations for the article were not a hill worth dying on. The critical information for feature setup and use still lived in the article, and the client was happy with the outcome.

Those facts sit at a higher priority level than my own preconceptions of clarity. The PM’s edits were egging me to step into the ring, but what was the point? What more was there really to gain?

This is difficult to accept because it feels like compromise, but sometimes the only way to win the fight is to say no to it altogether.

What the Evidence Shows

There is research that helps explain why this instinct matters.

A meta-analysis by Avraham N. Kluger and Angelo DeNisi examined how feedback affects performance across organizations. They found that feedback reduced performance in more than one-third of cases because it shifted attention away from the task at hand and toward the person him or herself.

When people fixate on the feedback exchange, they lose sight of the outcome. In other words, you can lose the fight by trying to win every single round.

Choosing the Necessary Battles

So what does this look like in practice? Here are some suggestions:

• Guard the moments that break the user. If an edit introduces confusion into a critical workflow, step in. This is your responsibility.

• Let structure flex when meaning survives. If the information remains intact, even in a structure you would not choose, consider yielding. The user can still find their way.

• Speak once, then release. State your case clearly. Explain the risk. Then let it go if the stakes are low. Not every point needs to be pressed.

• Watch for patterns, not punches. A single edit rarely defines a document. Repeated patterns do. Save your energy for what persists.

The Crown and the Cost

Kilbane’s legacy was not defined by that final loss. Eleven years as champion cannot be undone by a single right hook.

But that last fight still matters. He ultimately chose to step into a fight he did not need to take.

That is the thread that runs through all of this.

As technical writers, we are not just deciding how to write. We are deciding where to spend our energy and credibility. Every edit invites us into the ring. The question is whether it is worth it.

The danger is not that we lose those fights. It is that we enter them unnecessarily.

When we do, we trade progress for control. We risk trust. We lose sight of what the document is meant to do.

The goal is not to prove that we are right. It is to preserve what matters for the user.

It takes discipline to step in when clarity breaks, to yield when it does not, and to let go when the fight offers nothing in return.

Kilbane lost his title not because he lacked skill, but because he took a fight that carried more risk than reward.

We do the same when we treat every edit like a championship bout.

Because sometimes, the loss is not the punch that ends the fight. It is stepping into the ring when you never needed to.

In memory of John Patrick Kilbane, whose family remembers his humility and love.

“In defeat, Kilbane was just as big as he had ever been in victory” (New York Times, 3 June 1923).

Share

Subscribe now

It flatters us.

It lets us imagine that we stand outside the machine with clean hands, translating complexity for whoever needs help. We are not the architect. We are not the executive. We are not the one setting the incentives, designing the dark pattern, or approving the surveillance model.

We are just the ones explaining how it works.

Just the writers.
Just the docs people.
Just doing the job.

But that fiction collapses the moment your writing starts making a harmful system easier to use, easier to scale, or easier to excuse.

Clarity is not automatically moral.

Clarity transfers power.

The moment you explain something clearly, you increase someone’s ability to act. Sometimes that is good. Sometimes it is generous. Sometimes it is the difference between a frustrated user and a capable one.

And sometimes it is something uglier.

If your work removes friction from abuse, you are not merely describing the machine.

You are helping it run. You are oiling it.

So the real question is not, “Am I just doing my job?”

It is not even, “Did I build the harmful system?”

It is this:

At what point does explanation stop serving the user and start serving the harm?

Clarity is not one thing

Writers talk about clarity as if it were a single virtue.

It isn’t.

There are levels to it, and pretending otherwise is one of the ways we avoid responsibility.

The first level is descriptive clarity. This is simple explanation.

• What is the thing?

• What does this system do?

• What does this term mean?

You are helping someone see what is there. Neutral.

The second level is operational clarity. You are helping someone use the tool.

• Click here.

• Configure this.

• Set the parameter.

You are increasing capability. Again, neutral.

The third level is strategic clarity. Strategic clarity helps someone use the system more persuasively, more profitably, or with less resistance.

It does not merely help someone operate the machine. It helps them optimize it.

It smooths perception.
It anticipates objections.
It softens the language around the ugly parts.

It teaches people how to keep the machine running without alarming the people trapped inside it. That is no longer neutral.

Consider the differences:

• Explain what ad targeting is: descriptive.

• Explain how to configure tracking pixels: operational.

• Explain how to maximize behavioral capture while softening the language around surveillance: strategic.

When strategic clarity becomes complicity

The moral line is crossed earlier than people want to admit.

Most people only feel comfortable discussing ethics when the example is cartoonishly evil.

Genocide.
Forced labor.
Historical atrocity.

That is convenient.

If the standard is catastrophe, most white-collar professionals get to go home feeling innocent. Their work may be manipulative, extractive, or deceptive, but at least it isn’t that.

This is moral cowardice disguised as sophistication.

You do not need an extreme case to see where the problem begins.

It begins with strategic clarity.

Strategic clarity does not merely help someone use a system.

It helps them use it without resistance.

You see it in onboarding flows that teach teams how to increase “engagement” through variable rewards and compulsive loops that look suspiciously like slot-machine mechanics.

You see it in documentation that helps growth teams harvest more behavioral data while calling it “personalization.”

You see it in consent-flow guidance that explains how to improve opt-in rates by making refusal less visible, less convenient, less legible.

By the time the writer says, “I’m not hurting anyone. I’m just explaining the feature…” the real work has already been done.

Because strategic clarity often depends on something else: euphemism.

Writers like to believe the ethical problem lives in the system itself. Yet, sometimes it lives in the nouns:

• Surveillance becomes signal enrichment.

• Manipulation becomes friction reduction.

• Compulsion becomes engagement optimization.

• Data extraction becomes experience personalization.

• Deception becomes streamlining the user journey.

This is not cosmetic language. It is moral deodorant.

A euphemistic pop-up cookie consent window

Euphemism does not just soften reality for the user. It softens it for the writer. Once the language is cleaned up, the work no longer feels like harm. It feels like optimization.

Language does not merely report reality. It frames it. It determines what is seen clearly and what remains obscured.

A euphemism places distance between an action and its human meaning. Once that distance exists, people can keep working.

Upsells move faster.
The documentation looks cleaner.
The system becomes easier to defend.

Writers are particularly dangerous here because we specialize in removing friction from language. We know how to make something sound coherent, reasonable, and inevitable.

We can make an ugly process feel normal or make a predatory workflow read like a standard operating procedure.

That is a professional skill.

It is also a moral liability.

Because the more elegantly you disguise harm, the more implicated you become in it.

Examining the morality of clarity

“I’m just the writer.”

It is one of the most reliable refuges in the profession.

And to a point, it is true. Writers do not design every system they document. They do not control the incentives behind it. They are rarely the ones deciding how aggressively a tool will be deployed.

The relevant consideration is whether our labor makes a system easier to use, harder to resist, or easier to excuse.

We already understand this principle when the outcome is positive. We argue that documentation improves adoption, clarity reduces support costs, and good writing builds trust and helps systems scale.

Fine.

Then we cannot claim writing is powerless when it serves something harmful. That is not neutrality.

It is self-protection.

So when the ethical tension appears, the writer needs a test.

Ask yourself:

Who benefited from the friction I removed?”

If clarity makes legitimate work easier, it is serving the user.

If clarity makes manipulation, surveillance, deception, or exploitation easier, it is harming the user.

That distinction changes how a great deal of professional writing begins to look.

Some “best practices” are techniques for making unacceptable systems feel administratively normal.

Some “clear communication” is enablement.

What your clarity serves

Writers like to imagine themselves as translators standing outside power.

Often they are not outside it at all.

Often they are inside it—refining its language, smoothing its edges, and helping it travel farther than it could have gone on its own.

That is why clarity alone is not enough.

A sentence can be clean and still corrupt.
A document can be useful and still mislead.
A writer can be precise and still be morally compromised.

The real question is not whether your prose is effective.

The question is what your effectiveness serves.

If your writing helps people see clearly, act honestly, and accomplish legitimate work, clarity is a gift.

But if your writing helps manipulation, surveillance, or deception operate more smoothly and encounter less resistance, your sentences are not innocent.

They are accomplices helping the machine deceive its users.

At 7:00 a.m., I was on a call with an engineering manager and a lead staff engineer, talking through the high-level goals of updating an aging API. We discussed whether the existing sprawl of .rst files should be consolidated into a single .yml. We sketched a rough order of operations. Nothing unusual. This was squarely in my lane.

At 8:30, I rolled straight into a content score strategy meeting. The stated goal was to increase product adoption. I listened, asked a few clarifying questions, took notes. Still fine.

At 9:15, a last-minute calendar invite appeared: a product revenue goals meeting. I accepted without thinking. I understood the context. I knew how the product was positioned. I wanted to be useful.

Later that morning, a quick pre-lunch coffee chat with a PM turned into a working lunch. I shared an idea — something a senior leader had mentioned earlier that day — about how the PM might expand the addressable market for his product. He was receptive. The conversation felt productive. Necessary, even.

By early afternoon, I finally sat down to write.

The task was straightforward: a process article explaining how to ingest data into a non-Snowflake data warehouse. A concrete audience. A known workflow. Clear constraints.

But halfway through the introduction, I stalled.

I found myself wondering whether there was a way to increase adoption through more persuasive framing. Whether this doc could do more. Whether the product was being undersold. Whether the introduction should carry some of the strategic weight I’d been hearing all day.

The writing slowed. The sentences softened. The clarity blurred.

Nothing had gone wrong that day.
And yet the writing was worse for it.

Awareness Is Not a Single Thing

Technical writers are exposed to more information than most roles. We sit downstream of strategy and upstream of users. We hear about risk before it materializes. We understand consequences before they become visible.

That level of exposure creates a dangerous assumption: that awareness naturally implies responsibility.

It doesn’t.

There are two fundamentally different ways to hold awareness. Confusing them is how writers lose clarity without realizing it.

The first is investment.

Investment is awareness that becomes action in service of the writing’s quality. It is where judgment is exercised, defended, and carried through. Investment creates ownership.

A technical writer is rightly invested in the following:

• Craft of writing

• Precision of language

• Coherence of the user journey

• Faithful translation of established goals into something users can actually understand

When awareness measurably improves clarity at the point of use, it belongs here.

The second is engagement.

Engagement, not as the term is commonly used, is a disciplined form of awareness without authorship. It is the deliberate choice to understand context without shaping outcomes, to hear pressure without absorbing it, and to remain informed without allowing that information to redefine your role or writing.

Engagement looks like the following:

• Tracking goals you do not own

• Understanding risks you are not responsible for

• Holding information you must not act on

• Refusing corrective framing or advocacy in the writing

Engagement allows you to situate your role accurately without conscripting it into broader agendas.

Why Writers Don’t Make the Distinction

Being a technical writer places us in a narrow band of visibility. We are close enough to see failure forming before it becomes visible to others. We can recognize the misunderstanding that has not yet occurred and the decision that will age poorly. At the same time, we are far enough from power that we cannot redirect the outcome.

Being in this band of visibility, involvement often begins for reasons that have little to do with the role or writing:

• White Knight Syndrome. The writer compensates for what should have been decided better. The writing shifts from explanation to rescue, and loses its ability to describe outcomes without bias. What starts as helpfulness settles into a standing posture, and the writing quietly absorbs responsibility it was never meant to carry.
  

• Fear of Withdrawal. The writer contributes to preserve relevance. Authority in the role is informal and conditional. It is granted at the discretion of stakeholders and can be withdrawn or reduced without notice. In that environment, saying “this is not my concern” carries risk. Restraint becomes grounds for exclusion, and the writer moves toward the periphery of information and assistance.

• Role Validation. The writer acts to justify their presence. When value is defined by insight and foresight, restraint resembles inactivity. Seeing a problem and not intervening becomes indistinguishable from not contributing. Over time, awareness converts into action to demonstrate usefulness, and the role absorbs responsibility not because it belongs there, but because silence is mistaken for absence.

Objections

The distinction between engagement and investment tends to surface resistance not because it is controversial, but because it runs counter to how teams behave under pressure. When outcomes are uncertain and responsibility feels diffuse, restraint is easy to misread.

What follows are not arguments so much as predictable reactions to a role that refuses to absorb pressure it does not own:

• “If you understand the problem, why wouldn’t you help solve it?” Our comparative advantage is description under constraint. While complexity, urgency, and incentives pull in different directions, the writing preserves meaning at the point of use. When writers begin shaping outcomes they do not own, the writing compensates for strategy. Language becomes persuasive rather than precise. The writing may appear more helpful, but it becomes less reliable.
  

• “We need everyone invested. This is a team sport.” Under pressure, teams collapse shared awareness into shared ownership. Accountability thins and clarity degrades. Cross-functional collaboration does not require cross-functional authorship. The technical writer collaborates widely so that clarity has a single steward. Documents written to support outcomes read differently than documents written to preserve understanding. The latter endure longer.
  

• “This Doesn’t Work in Startups. Everyone Has to Pitch In.” Early-stage environments intensify, rather than invalidate, this distinction. Strategy shifts quickly. Roles blur. Pressure is constant. Under these conditions, clarity becomes harder to maintain and more valuable. When everyone is improvising, someone must preserve what was decided, what the product currently does, and what the user can reasonably understand. Tracking instability without internalizing it keeps the writing intact while the organization adapts.

Choosing Where Care Belongs

When writers fail to distinguish engagement from investment, nothing breaks immediately.

The documents still ship.
The meetings still happen.
The writer still appears helpful.

That is what makes the drift difficult to detect.

However, article introductions begin to persuade instead of orient. Descriptions soften to protect decisions. Processes quietly compensate for strategy. This is why the distinction between engagement and investment matters.

This framework is an argument for owning precisely.

The technical writer does not exist to stabilize organizations, rescue strategies, or absorb ambient anxiety. The role exists to produce clarity that survives pressure, including pressure from well-meaning teammates who want everyone invested in everything.

Engagement keeps the writer informed. Investment preserves the integrity of the writing. Confusing the two does not make teams stronger. It makes clarity weaker.

Early accounts describe Columba walking the island alone at dawn. He prayed along the waterline, where sea and sky blur into one another and the sound of crashing waves carries a strange resonance. The solitude felt less like absence and more like anticipation.

Columba believed God spoke out there by the waves. The loud breaking of the sea pierced the quiet of his prayers. By Columba’s own admission, the place itself seemed to listen.

Iona came to be known as a “thin place.” Pilgrims would later say that standing there felt like standing on a threshold, as if the mundane world had lost its grip. Heaven felt closer, not because of emotion or imagination, but because the earth itself reached out for it.

The Celts did not treat inspiration as a force of fate that arrived randomly. They believed it emerged where place and presence met: mountains, islands, rivers, shores. Where you stood shaped what you heard.

Maybe we don’t walk rocky coastlines expecting a divine encounter, but we still recognize this truth instinctively. Some places sharpen us. Others dull us. Some environments make our work feel strained and brittle. Others make it feel like breathing. The difference is rarely effort. It’s location.

When Work Has No Threshold

In the world of remote work, inspiration and productivity are not a given. If you’re a remote worker, you already know this!

Our work easily loses its sense of being set apart. The table where we eat becomes the desk where we write. The chair where we rest becomes the chair where we labor. Over time, the boundaries thin in the wrong direction.

This erosion shows up in documentation. Writers think carefully about structure, clarity, and audience, yet rarely about the physical conditions under which the writing happens. The assumption is that competence alone carries the work. But when every day begins in the same room, with the same light and the same noise, the craft starts to feel flat.

Documentation is conceptual, but writers are embodied. We write with nervous systems, senses, and emotions. The places we choose shape how well we listen, how patiently we think, and how honestly we translate complexity into language another human can use.

What the Ancients Understood About Attention

Columba did not find inspiration in the hustle-and-bustle of life. He walked the edge of land and ocean. Moses climbed Sinai. Jesus went into the wilderness beyond the Jordan. Scripture consistently treats insight as something received away from distraction, in landscapes that demand attentiveness.

These stories suggest that focus is not merely an act of will. It is often a response to environment. Certain places quiet unnecessary noise. Others heighten it. Thin places do not guarantee inspiration, but they create the conditions in which inspiration can be noticed.

Modern work culture tends to treat environment as accidental. The Celts treated environment as formative. They believed place could tutor the soul. That assumption feels foreign to many of us in the West, yet it explains why their language still resonates today. We haven’t stopped needing places that help us pay attention.

Why Documentation Suffers Without Place

Good documentation depends on posture as much as process. Writers working from environments that foster attention tend to write more clearly. They notice friction sooner. They resist unnecessary complexity.

Obviously, a thin place does not write a document for you. It simply removes enough noise that you can hear what matters. When the environment steadies the mind, prose steadies with it. When the surroundings feel real, the writing does too.

Columba didn’t bring inspiration to Iona. Iona made him receptive. The same dynamic applies to modern writers. Place becomes a quiet collaborator in the work.

Environmental psychology supports this intuition. A widely cited study from the University of Michigan found that exposure to natural environments improved directed attention and working memory, even when participants were not deliberately trying to rest. Urban environments, by contrast, depleted these cognitive resources.

The implication is straightforward. Our surroundings directly affect our capacity for clarity. Thin places may be described in spiritual language, but they align closely with what research shows about how human attention actually works.

Learning to Work Where You Can Hear

For a few months now, I’ve been working from the atrium in the Cleveland Museum of Art once a week. It’s become a kind of thin place to me. Completed in 2014 under the guidance of Uruguayan architect Rafael Viñoly, the atrium is a soaring, glass-enclosed space that sits at the heart of the museum, noted for its light, massive scale, and integration of old and new architectural styles. Viñoly created a unique space that feels connected to the nature of Ohio’s north shore but insulated from its harsher elements. And perhaps most importantly, it is surrounded by one of the greatest, most diverse art collections in the world. The atrium speaks.

I noticed that my days in the atrium were always, without exception, spent well. I was more productive, more organized, and left more fulfilled. The atrium didn’t solve my life’s problems or reveal the company’s next steps, but it gave me a place to indulge beauty, discover solutions, and find God somewhere between.

So, my charge for you is the following:

1. Identify your thin place by paying attention to your body. Notice what happens to your breathing, your pace, and your emotional tone. Calm and clarity are better signals than comfort or convenience.

2. Match the place to the phase of writing. Drafting often benefits from environments that feel alive. Editing often requires quieter, more grounded spaces. Let the task guide the location.

3. Create a threshold for work. Even in remote life, choose places that signal transition. A café, a museum, a park bench, or a specific seat can mark the difference between labor and rest.

4. Let place discipline your posture. When the environment invites presence, you push less and listen more. The writing becomes responsive rather than forced.

Returning to the Shore

When I sit in the skylit atrium, writing doesn’t feel like work. It feels like breathing. The space removes the urgency to produce and replaces it with attention.

Columba walked the shoreline because it taught him how to listen. We find our own shores in different ways, but the lesson holds. Our best work rarely appears out of nowhere. It rises from the ground beneath us.

Where we stand still shapes what we hear.

Share

Subscribe now

But that’s not the kind of resilience technical writers need.

Technical writers don’t burn out from difficult work. They burn out from undefined boundaries. You get pulled in every direction. The scope of work expands without warning. You inherit missing context and contradictory inputs.

Then gradually, you become whatever your stakeholders need you to be. And in a rare moment of clarity, you catch yourself asking:

• Why am I doing what I’m doing?

• Why does the work no longer make sense?

Resilience begins before that point.

It begins with structure.

The Shape of Real Resilience

Resilience often gets described as a moral quality. It is something earned through hardship or displayed under pressure. But for technical writers, resilience isn’t heroism. It’s not toughness, endurance, or a willingness to power through.

Resilience is the ability to return to a coherent form after impact.

Having resilience gives you operational advantages:

• Unshakeable under shifting requirements. When the product changes, you don’t panic.

• Deeply valuable in ambiguous environments. When everyone else starts spiraling, you stay grounded and teams notice.

• Less susceptible to burnout. A stable shape can prevent burnout that results from trying to be all things to all people.

In a 2024 study of over 2,000 firefighters, researchers found that those with high self-concept clarity — a well-defined, coherent sense of identity — were significantly more resilient and far less likely to experience burnout.

The researchers concluded that “self-concept clarity can not only directly affect the working state... but can also influence job burnout and improve work engagement through the mediating effect of resilience”.

You build resilience while things are calm. And you build it by defining who you are and designing conditions that let you stay that way. But before we can build it, we need to understand what resilience actually is.

Why We Don’t Think of Resilience This Way

If resilience is really structural — a product of self-definition and environment — then why don’t more writers see it that way?

Part of the problem is framing. We’ve been taught to think of resilience as a personal virtue:

• Calm under pressure

• Patience with ambiguity

• Endurance when timelines compress or scope expands

Under that lens, resilience becomes a matter of character. You either have it or you slowly develop it through repetition, strain, and the right mix of self-regulation techniques.

When the strain shows, the response is always inward: breathe, adjust your attitude, manage your energy, take a nap. This isn’t bad advice, but it’s incomplete.

The environments we operate in don’t just challenge us. They define us. And most technical writers have been conditioned to adapt to that definition. We’ve been rewarded for absorbing ambiguity, for filling in the gaps, for being helpful in ways that quietly exceed the shape of the role itself.

As we keep absorbing this ambiguity, we condition ourselves to believe that this is resilience: the willingness to stretch further than we should, to recover without complaint, to stay upright no matter how many inputs contradict each other.

But that’s not resilience. That’s distortion.

The corrective starts with self-definition.

Self-Definition: Your Shape

Technical writing attracts conscientious people — thoughtful people who take pride in being useful and who quietly shape their identity around being dependable. These are strengths, until they aren’t. Because over time, usefulness can start to replace definition.

Early in my career, I began to notice a pattern. The writers who struggled most weren’t the ones with the weakest skills or shallowest experience. They were the ones who lacked a defined shape. They stepped into every gap. They treated every request like a mandate. They believed their job was to be helpful.

And when things inevitably got messy — shifting requirements, clashing stakeholder inputs, unexpected fire drills — they had nothing to return to. No fixed center. No grounding principle. Just a slowly expanding tangle of obligations they never actually agreed to.

Most engineers can explain the constraints that shape their architecture. PMs can articulate what they’re optimizing for. Designers, analysts, even sales leads tend to have some north star for their work.

That’s why self-definition isn’t a branding exercise or a manifesto. It’s a structural necessity. And often, it’s private.

“I transform raw technical intent into usable information. I don’t generate that intent myself.”

“My value is clarity, context, and coherence — not inventing features, rewriting roadmaps, or rescuing broken processes.”

These are quiet lines. But they change everything.

Because once you define your shape, the work starts to stabilize. You stop reacting to every new ask. You start making deliberate choices. And the people around you begin to follow your lead, often without even realizing it.

Resilience begins here.

However, self-definition only matters if the environment reinforces it.

Environment: The Structure Around the Shape

You can be clear about your role. You can know the shape you’re meant to hold. But if everything around you tugs at that shape with incomplete inputs, mismatched expectations, or an endless drip of undocumented edge cases, the clearest self-definition starts to blur.

Technical writers feel this tension more acutely than most. We sit at the intersection of engineering, product, support, sales, marketing, and design. Each group has its own assumptions about what documentation is, how it should be created, and where it fits within the product landscape.

It’s easy to contort yourself to meet every one of those expectations. It feels like the responsible thing to do. However, this is erosion by accommodation. And you can address this by designing the environment around you to support the shape you’ve already defined.

I saw this clearly during a conversation with a young writer named Mike. He was a few months into a new role and already underwater.

“Hey Mike, how’s the writing coming along for the security feature release?”

“Kevin,” he said. “I’m chasing JIRA tickets. I’m reading Slack threads. I’ve had multiple meetings with engineers, and somehow I feel like I understand less than when I started.”

I nodded. “So... what’s your next move?”

He sighed. “I’m going to build my own demo, start to finish, and test the security flow myself.”

Mike thought he needed more grit and perseverance. What he needed was to define his environment. I used to operate the same way. Sometimes I still catch myself doing it. But there’s a better approach that doesn’t rely on personal heroics.

I told him something simple:

“Have the engineers and PMs write the foundational draft.
They give you the marble slab.
You carve the statue.”

He looked surprised. Maybe even relieved.

Environment design isn’t about control. It’s about structural clarity:

• Engineers provide the technical intent.

• PMs provide the rationale, constraints, and narrative.

• Writers refine for clarity, sequence, and tone.

This is the second half of resilience.

The Quiet Conclusion

Technical writing will always expose you to volatility. It will appear as shifting features, incomplete inputs, unclear ownership, timelines that compress, or feedback that arrives too late.

But when you’ve defined yourself and designed an environment that reinforces that definition, the volatility stops being existential. It becomes part of the landscape you’re built to move through.

Resilience isn’t earned through endurance. It’s protected through structure.

Everything else is just noise testing the shape.

So we closed the door.

At the time, it felt strange. The loss introduced uncertainty and disrupted our routines. Yet it also created something needed: space. In that space, new opportunities took root. We began working with a client in a new industry, whose product team collaborated openly, and whose feedback cycles made us better writers.

We found ourselves grateful for the years we had with the first client. And we found ourselves grateful that the chapter had ended.

Writers Resist Endings

In the world of technical documentation, endings rarely come with ceremony. Usually, a project slows down, or a client’s priorities shift. A feature might be deprecated, but its documentation lingers in the sidebar for months because no one wants to be the one who removes it. Writers often hold on to engagements long after their usefulness has faded, not because the work benefits the product, but because letting go feels uncomfortable.

We know how to accumulate work. We do not always know how to release it. However, every mature documentation practice depends on pruning. Without it, teams continue producing text that no longer serves the reader, the product, or the strategy.

The deeper issue is not productivity but attachment. We cling to what once was, even when it no longer supports what could be.

Thanksgiving and the Overlooked Gift of Loss

This week in the United States, many of us pause for Thanksgiving. Families and friends gather to express gratitude for what we have — safety, provision, food, and, most of all, one another. But do we give thanks for what we no longer have? Gratitude tends to reach only in the direction of provision, not loss.

Closing the client relationship taught us that gratitude stretches beyond “having” into “not having.” Thanksgiving can encompass the work that shapes us, and it can encompass the moment when we outgrow the work. The departure from our client freed us to step into a partnership that renewed our creativity, sharpened our thinking, and connected us with people who care deeply about their product.

Thanksgiving, at its best, widens our view of what is good. It helps us see that periodic pruning is healthy for our work, and our lives, so that something new can grow.

Why Pruning Strengthens Documentation Teams

Letting go can strengthen documentation teams. Closing the client relationship revealed that our best work requires alignment, trust, and rhythm. Those conditions had faded, but we hadn’t noticed how much until we entered a new engagement with stronger collaboration. The contrast clarified everything.

Good documentation depends on clarity of focus. When we hold on to projects or partnerships solely because they are familiar, we dilute that focus. We spend energy maintaining what no longer needs to be maintained. We become archivists instead of writers.

But when we prune well, we reclaim our attention. We renew our craft. We open ourselves to projects that ask more of us and allow us to give more in return.

Practicing Grateful Loss

Organizational psychologist Connie Gersick studied how teams evolve and found that progress rarely happens through steady continuity. Instead, teams experience what she calls “punctuated equilibrium.” They move forward in bursts after releasing assumptions, habits, and commitments that no longer serve their goals. The shift often occurs at the moment they acknowledge a necessary ending, ranging from deadlines to contract expirations.

In other words, we operate best when we learn to let go of things.

Here are some practical ways in which we can intentionally, but gratefully, let go:

1. Schedule intentional pruning cycles. Every quarter, review your documentation library, client roster, and internal processes. Identify what has stopped producing value. Name it honestly. Close chapters before they close on their own.

2. Capture the gratitude on both sides of the loss. Document what a relationship taught you while you had it — skills learned, domain expertise developed, or processes refined. Then name the gains that emerged after the relationship ended. This creates a culture that honors the past without being bound by it.

3. Use the freed capacity deliberately. You don’t need to rush to fill the new space with noise. Use it to deepen relationships with aligned clients, explore new industries, or rewrite old documentation with clearer thinking.
   

When Loss Makes Room for Gratitude

When we stepped away from that client a year ago, it felt like a loss. It was. But it was also a release. It created space for something that did not yet exist but was waiting for us to make room.

As Thanksgiving arrives again, we find ourselves grateful for the years we spent building that first relationship. And we are grateful that the relationship concluded when it did. The ending was not a retreat from growth but the beginning of it.

We sometimes imagine gratitude as an inventory of what remains in our hands. Yet the past year taught us something gentler and more surprising: sometimes the most meaningful gifts arrive through subtraction.

Thankfulness expands when we learn the art of loss.

Share

Subscribe now

Within the first 30 minutes, I’d made a thrilling descent amongst stones and tree roots followed by a punishing climb. The 20 pounds on my back grew heavier with every step. The map showed I was progressing. AllTrails claimed the loop would take 90 minutes to complete. In my head, I’d already completed the first third.

Then about 15 minutes later, it happened.

I was halfway through the hike, deep in the woods, standing at the lowest elevation on the loop when my iPhone signal died. The location marker froze and placed me miles away from the trail. The woods felt quiet and impenetrable in that way they do when you suddenly realize you don’t know exactly where you are.

Thankfully, I had downloaded the map.

Less thankfully, I hadn’t actually studied it.

I misread turns. I trusted instincts I hadn’t honed. A couple of times, I ignored the trail entirely because the direction “felt” right. By the time I finally committed to following the map instead of my confidence, I had walked 2.8 miles just to complete the 1.8-mile loop.

Eventually, I was back at my car, unloading the weight from my shoulders and thinking about how easily a simple walk becomes something else when you’re unprepared.

The Shape of Service

Someone had walked this trail long before I did, and they hadn’t just left footprints. They had left guidance: quiet, intentional choices embedded in the map. The

switchbacks were traced with care, elevations noted, landmarks called out before they could be missed. Even the downloadable version felt deliberate, as if the person behind it anticipated the exact moment when the world would go quiet and my instincts would fail.

The mapmaker’s attention to details still reached me. And making someone else’s path navigable in your absence is service. Service is foresight translated into structure, care distilled into sequence, preparation made visible at the point where someone is most likely to get lost.

You go first so someone else doesn’t have to go blind.

Why Service Goes Unseen

Many writers don’t view their work as contribution. The reasons are subtle, psychological, and entirely human.

Our work succeeds in silence. When documentation does its job, nothing dramatic happens. There’s no visible transformation, no acknowledgment, no obvious indicator that clarity was delivered at precisely the right moment.

Proficiency minimizes the labor. As a writer’s skill grows, what once took hours becomes instinct. That ease begins to feel like insignificance. The better we get, the less we feel the weight of what we’ve made.

Accuracy becomes our compass. Feedback focuses on inaccuracies, rarely on what helped the reader succeed. Gradually, we treat error prevention as the whole craft and lose sight of our responsibility to create understanding.

We work far from the stakes. We see structure. Readers feel risk. The difference in perspective makes it easy to forget the impact of one unclear step.

How do we overcome this?

Practicing Service

Our task is not simply to transmit information but to shape a path another person can walk. These practices keep the writer aligned with the reader, the system, and the stakes.

Look for the human before the system. Every system emits two signals: how it works and how it is experienced. Writers who listen only to the logic produce clear but hollow work. Service begins by noticing where frustration spikes, where confidence drops, and where ambiguity multiplies.

Notice the knowledge you almost forgot you learned. With experience, certain insights feel too obvious to mention. They are not. What feels instinctive to the writer is often the very thing the reader needs most. When something seems unnecessary to explain, that is usually the signal to explain it.

Let confusion guide your structure. Your confusion is data. The steps that took too long, the answers that didn’t land, the moment the product contradicted itself. These are the markers of where a reader will slip. Structure the work around what confused you, not what flatters your expertise.

Write for the reader who will arrive tired. Most people come to documentation when their patience is gone and the stakes feel high. Write for that reader: the one who has already tried three things that didn’t work. Clarity is an act of care.

These practices don’t make the work easier. They make the work honest. They return the writer to the role of someone who goes first, notices what matters, and leaves behind a path someone else can trust.

Path You Leave Behind

A good document erases its own footprint. A clear sentence hides the drafts that shaped it. This invisibility defines the contribution. Service directs and shapes someone else’s experience without asking for credit.

That is the quiet power of service: you guide people you will never meet through moments you will never see. You go first, make sense of what’s in front of you, and leave behind clarity for someone else to trust.

Your users may move through your documentation without a second thought. They won’t know who walked the terrain before them or who noted the parts others missed.

But you will.

And that is enough.

So, I asked him how he manages to be productive in the midst of all the chaos. His answer surprised me.

He doesn’t try to be productive. He just lets it happen.

He’s accepted that there are times — maybe even days — when life simply doesn’t allow for productive work. Family, travel, and interruptions happen. On those days, forcing output almost always results in poor or even counterproductive results. Instead, he lets productivity come to him. If things quiet down later in the evening after the kids are asleep and he catches a second wind, he rides the gusts as far as they’ll take him. If he finds a quiet moment mid-day between meetings, he takes advantage of it.

He doesn’t create a context for productivity. He lets the context create the productivity.

The Problem with the Grind

Most of us in tech and SaaS industries live under the myth that productivity is a constant state we can summon at will. We schedule deep-work blocks, buy focus apps, and measure our worth by how much we produce before lunch.

But anyone who’s worked in documentation or product knows this: you can’t brute-force clarity. When you sit down to write in the wrong frame of mind — in chaos, distraction, or fatigue — the output might look like writing, but it isn’t thinking. The sentences are there, but the insight isn’t.

We grind because we’re afraid to stop. Yet the grind often gives us more words and fewer ideas. My client’s perception stood in stark contrast to this. He understood instinctively that productivity is a rhythm.

He recognized that forcing output ignores the natural cycles of attention and recovery that creative and analytical work require. The same truth applies to technical documentation. There are moments when your brain, your product, and your team’s feedback align.

Those are the moments when you “should” write, the windows when the work deserves your effort. The rest of the time, writing simply because you “can” often means producing text that will be rewritten tomorrow.

Defining Our Terms

Let’s name the distinction clearly:

• Working when you can means using available time, regardless of readiness. It’s rooted in control and the idea that productivity can be summoned on demand.

• Working when you should means aligning your effort with the moment’s potential. It’s rooted in wisdom and recognizing when the conditions support meaningful progress.

The first approach looks productive, but the second actually is.

Why This Matters in Documentation

Technical writing depends on rhythm. The best docs aren’t born from uninterrupted grind sessions but from cycles of gathering, reflection, and synthesis. You need moments of reading product specs, watching a demo, testing the workflow, and then letting your mind connect the dots.

The grind treats writing like an assembly line. But documentation is closer to design. It thrives in intervals of focused creation punctuated by rest, review, and revision. As writers, our goal isn’t to produce constantly but to produce consequentially.

In a study on mental fatigue and time structure, Meijman and Mulder found that how we organize our working hours directly shapes our cognitive performance. When work was arranged in continuous, unbroken blocks, subjects experienced faster onset of fatigue and lower quality of focus. But when the same workload was distributed across shorter cycles of effort and recovery, both accuracy and endurance improved significantly.

Their findings suggest that productivity isn’t just about how much time we spend working, but how that time breathes. The human mind performs best when work is structured rhythmically, not relentlessly. Effort and rest should alternate with intention.

How to Work When You Should

Here are a few practices to help tune your writing rhythm instead of fighting against it:

1. Track your natural peaks. Take note of when in the day your mind feels clearest. Schedule your hardest thinking tasks around your natural peaks rather than your calendar.

2. Distinguish busy time from deep time. Busy time checks boxes. Deep time changes outcomes. Protect your deep time by reducing context switching and Slack noise.

3. Use friction as feedback. When writing feels forced, stop! Go test the product, read an issue, or just walk away. The friction is information. It’s your brain telling you conditions aren’t ready.

4. Honor rest as part of the process. A rested writer is strategic. Rested attention yields cleaner drafts, fewer revisions, and more authentic tone.

Closing

When I ended that call with my client, I thought about how rare his approach was. He wasn’t lazy or undisciplined. He was discerning.

He had learned that productivity isn’t a faucet to be turned on so much as a tide to be ridden.

Good technical writing — and good living — requires that same discernment.

Work when the tide comes in, and wait when it goes out. Because ultimately, the grind is a lie. Only rhythm is real.

Subscribe now

Share

Troy’s contract expectations spelled it out in a single sentence:

Transfer documentation from one platform to another. Improve the content as appropriate.

Two phases. Ninety days. The kind of engagement meant to test competence without commitment.

But Troy didn’t wait for instructions. On Monday morning, he signed up for the company’s product and started implementing it like a customer would: API calls, authentication tokens, failed requests, the works. He wanted to see what users saw.

By Tuesday night, he’d built a small demo app that ran end-to-end. He filled a TextEdit file with workflow challenges, questions, and perceived bugs and sent the list to the product manager and engineering team.

This wasn’t a show of expertise. It was a demonstration of understanding and care.

That message of challenges, questions, and bugs hit harder than he expected.

The engineers realized this wasn’t a passive writer waiting for specs. Troy was someone inspecting the product the way a user would, without bias, without guardrails. His questions surfaced blind spots they’d quietly accepted as “edge cases”.

By Wednesday, the product director added him to the next design review. By Friday, three different departments had looped him into their Slack threads.

Reframing Visibility

Most people treat visibility like politics. It’s something you either have the stomach for or don’t. They assume it belongs to the self-promoters, the managers with volume, the ones fluent in meetings.

Technical writers, in particular, recoil from that world. We’re trained to believe that competence should be enough. If the work is solid, consistent, and useful, it will speak for itself. That belief feels moral. It sounds like fairness, meritocracy, and craft. You do good work. You stay humble. People notice.

Except they don’t.

“Let the work speak for itself” is comforting because it preserves our sense of purity. It lets us keep our heads down, avoid politics, and imagine that the system rewards substance.

But most systems don’t.

That’s the quiet irony: the writers most devoted to substance often remain the least recognized because they refuse to design for perception. Their work vanishes precisely because it’s clear, accurate, and frictionless.

The result is structural asymmetry.
The loud ones inherit attention.
The quiet ones hold the system together.

So the question becomes: how do you turn visibility from performance into clarity?

How do you make your value seen without distorting it?

Visibility Through Review

Most people treat a review as a checkpoint, a perfunctory request for sign-off before publishing. But a review can be more than that. It can be an opportunity to broadcast your value.

When you invite Support, Product Management, Account Management, and Sales into the review process, you aren’t just collecting feedback. You’re extending clarity outward. Each reviewer gets a window into how you think, how you structure, phrase, and prioritize information.

That invitation does two things at once:

• It improves the documentation through diverse perspectives.

• It makes your work and your value visible across the organization, without self-promotion.

That visibility lands differently for each stakeholder:

• The support engineer sees you clarifying edge cases that reduce ticket load.

• The account manager notices you linking features to outcomes that drive client renewals.

• The product manager realizes your writing closes gaps in their own understanding.

To each of them, you stop being the person who “writes the docs” and start becoming the person who makes the product clearer, stronger, easier to sell.

Visibility built on generosity lasts longer than visibility built on noise. When people feel how your clarity makes their work easier, they remember the source.

Write by Testing

Every strong writer eventually learns this truth: if you want to explain a system clearly, you have to break it first.

Testing your own documentation isn’t clerical diligence. It’s diagnostic intelligence.

By installing, configuring, and deliberately failing through each workflow, you see the gaps between how a product is supposed to work and how it actually behaves.

This is where writing starts to resemble quality assurance. The instructions that don’t match the interface, the error message that surfaces too late, the workflow that dead-ends, these all reveal product blind spots.

Troy understood this early. The first thing he did was test. By treating the product like a customer, he surfaced the assumptions no one else had questioned. This instinct separates technical writers who document systems from those who improve them.

When you raise these issues, people notice. Engineers and designers start sending prototypes. Product managers tag you in feature discussions. You are able to provide feedback through fresh eyes and unfiltered logic.

That’s how credibility spreads. The more problems you quietly prevent, the more indispensable you become. Teams remember the person who saved them from embarrassment longer than the one who wrote the perfect paragraph.

Track the Change

When the next release ships and priorities shift, it’s easy for others to forget what you contributed. In fast-paced teams, that forgetting is almost structural. One recent study by Gorbatov et al. found that even when workers performed well and had strong expertise, those who didn’t make their contributions visible were less likely to be seen as valuable by employers. The final act of delivering your work is preserving the memory of its impact.

Show what changed because you were there. The friction you removed. The confusion you prevented. The trust you helped restore.

A few ways to do this:

• Keep simple records that show the difference between what was and what is.

• Notice when support tickets stop appearing.

• Record when onboarding times grow shorter.

These aren’t status reports. They’re signals -- small, factual connections between effort and outcome. Collected over time, they form an institutional memory of reliability.

People begin to recognize the pattern. Every time the work feels clearer, the same fingerprints appear. Yours.

That’s how value becomes legible.
Not through promotion, but through pattern.
Not through noise, but through continuity.

Each improvement becomes a quiet receipt of trust, proof that the work mattered long after anyone remembers who wrote it.

Visibility Without Spectacle

Troy never tried to make himself visible. He made his work visible.

Without disregarding your commitment to quality and merit, you test relentlessly and capture the impact of your effort as an act of respect. You involve others because generosity builds trust faster than self-promotion ever could.

This kind of visibility begins where “letting the work speak for itself” ends. The work doesn’t speak on its own. It needs someone willing to make its value apparent without turning it into spectacle.

Over time, others notice. They recognize the pattern: everything you touch becomes easier to understand, easier to use, easier to trust.

You don’t have to advertise competence when your presence consistently reduces confusion. You don’t have to campaign for influence when others instinctively turn to you for clarity.

Delivering value keeps you around. Helping others see that value brings you into the room where decisions are made.

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.

When we started playing, something beautiful happened. The melody wove through the room, some harmonies rose instinctively, and we all sang together. For the first time, I suddenly heard those songs the way they were meant to sound: layered, alive, and communal.

It struck me how different that sound was from when I play alone. When I sing by myself, I focus on precision, on getting the timing right or keeping the rhythm steady. But when others join in, the goal shifts from precision to connection. The imperfections blend into something richer than any single voice or instrument.

And that’s exactly how good documentation should work.

The Solo Problem

Writing documentation can feel like a solo act. We open a new doc and sink into the lonely rhythm of words and screenshots. The product is complex, the release is due, and someone needs to “just get it written.”

But when documentation becomes a one-person show, it loses its texture. Without input from others, our words will sound accurate but hollow, like a song missing its harmony. The doc might explain how to click each button, but it won’t fully capture what the product means or why it matters.

That’s the solo problem: clarity without resonance.

Jam Sessions

A good jam sesh depends on the subtle interplay between players. The drummer listens for the guitarist’s rhythm. The vocalist adjusts their phrasing to the bass line. No one’s just performing their part in isolation. They’re responding to each other.

Documentation should function the same way. The best docs emerge from overlapping perspectives:

• Product Managers provide the vision (why this feature exists and what user problem it’s meant to solve).

• Engineers offer the mechanics (how it actually works under the hood).

• Product Marketing ensures alignment with the message that brought in the customer.

• Support reveals the pain points users encounter when theory meets reality.

Each group brings its own melody. When we listen carefully and blend their inputs, we end up with something that not only instructs but also sings.

The Claim

To ground this conversation, let’s name two kinds of harmony that matter in documentation:

• Technical harmony: Consistency between the doc’s content and the product’s functionality. This ensures accuracy, completeness, and trust.

• Contextual harmony: Alignment between documentation and the product’s larger story, like how it’s marketed, supported, and experienced by users.

Most writers focus on the first. Few teams consistently achieve the second. But contextual harmony is what transforms documentation from reference material into a living expression of the product’s identity.

In this way, great documentation isn’t just clear. It’s collaborative. It carries the voice of the whole team. When multiple contributors shape a doc technically and contextually, users come to learn how the product works, how it’s unified, and how it’s intentional.

Studies in organizational communication have shown that cross-functional collaboration increases both clarity and adoption. One relevant finding comes from Majchrzak, More, and Faraj (2012), who studied distributed teams and found that “co-created artifacts” — like documentation — lead to deeper shared understanding and higher team trust when multiple perspectives are integrated early in the process.

Their conclusion applies perfectly to our field. Collaboration isn’t a step in the workflow but the source of meaning itself.

So, this is the hidden virtue of stakeholder-rich writing: it reinforces the idea that the product is coherent, that every part fits together. The harmony among contributors builds harmony in the reader’s mind.

Practical Application

How do we turn solo drafts into jam seshes? A few practices make all the difference:

• Host a “Docs Jam.” Gather PMs, engineers, and support for a short, focused review session. Play through the draft live, asking: “What’s off-key?”

• Map contributors to their instrument. Assign each stakeholder a domain: product vision, technical accuracy, user empathy, brand alignment.

• Bridge to product marketing. The value proposition that won over the customer should be the same one that appears in the documentation. The docs should back up marketing’s promises.

• Capture the audience’s feedback. After publication, treat user comments like a post-show review. Adjust tone, clarity, and structure accordingly.

Each step is less about revision and more about resonance.

Closing

When my friends and I finished the set, nobody said much. We just smiled, knowing that something special had happened, and that none of us could have done it alone.

That’s what happens when a team writes in harmony. Documentation stops being a record of what was built and becomes a reflection of who built it.

When voices blend, clarity becomes resonance, and resonance becomes song. That’s when your documentation starts to sing.

Subscribe now

Share

In ordinary seasons I summon a kind of creative enthusiasm. There is joy in the hunt for clarity, in turning engineer-speak into human language. Some days writing feels alive, as if a single reworked sentence reveals a small truth.

But then autumn comes. The reservoir empties. It becomes harder to pretend there is meaning in distilling technical explanations into neat MadLibs templates: overview intros, conceptual articles, process docs, API definitions. They still get written, but with less conviction. The work becomes task, not craft.

Ecclesiastes offers a hauntingly simple truth: there is nothing better under the sun than to eat, drink, and find enjoyment in toil. That is the ideal, not merely to endure work, but to receive it as gift.

And yet I find more ennui than joy in mine.

Ennui is not the despair of collapse. It does not arrive with fire. It seeps in with fog. Hours blur, tasks repeat, nothing new emerges. The work feels necessary and yet inconsequential.

To admit this feels risky. What kind of professional confesses the work doesn’t always feel meaningful? Yet most of us drift through seasons when effort feels hollow. Ecclesiastes reminds us we are not the first: the Preacher surveyed wisdom, pleasure, wealth, toil — and found them all vanity.

The question is not how you work when meaning is present, but how you work when it evaporates. However, before exploring the how, let’s consider the what.

Ennui’s Shape

Ennui has a different texture than exhaustion. Fatigue asks for sleep. Ennui asks for meaning. It isn’t the ache of overuse but the thinness of repetition, the sense that nothing new waits beyond the next sentence or sprint ticket.

Philosophers have long wrestled with this void. Kierkegaard called it despair, the slow erosion of self when no “why” holds. Nietzsche offered a harsher test: eternal recurrence. If you had to live this day, in this form, over and over for eternity, could you affirm it? Would you embrace even the mundane, even the documentation edits, as worth repeating forever?

Camus, more defiant, described life as absurd. We hunger for meaning, and the universe returns silence. His answer wasn’t resignation but rebellion. He imagined Sisyphus, condemned to push his boulder up the hill only to watch it roll back down, as secretly free. The gods could sentence him to labor, but not to despair. His defiance was simple: to push well, to treat the stone as if it mattered.

I think of these men when the fog of ennui settles over my work. Technical writing lacks the drama of philosophy, but it forces you to live its questions. Is there meaning in distilling a technical explanation into a process doc that half your audience may skim? Is there dignity in structuring an API definition so that a future engineer doesn’t curse you at 2 a.m.? Or is it all vanity, one more entry in the endless churn of corporate production?

This is where philosophy presses into craft. Ennui strips away the illusions of inspiration, leaving the raw test: will you keep writing when the feeling is gone? Will you still order chaos into coherence for a reader you may never meet?

If meaning must be earned, perhaps it is earned here. When the work is stripped bare of reward, you choose to give it form. But how?

Defiance in Practice

When the reservoir runs dry, you learn to invent your own streams.

Over the years, I’ve developed ways to bypass ennui. None of them restore joy. They aren’t cures. They are small acts of rebellion against the void. They are little choices that keep my hand moving even when my heart resists.

1. Urgency through artificial deadlines

I often set myself deadlines tighter than necessary. A ticket due Friday becomes, in my mind, due Wednesday at noon. It’s a trick of the clock, but it works. Pressure transforms boredom into a fight. Suddenly I’m not drifting. I’m in a race where the words sharpen, because constraints demand precision.

Deadlines remind me that time itself is a boundary. Camus might call this absurd, but it’s a form of choosing. If the boulder must be pushed, then I can decide how steep the hill will be.

Psychologists call this job crafting, reshaping your work to make it more engaging. A recent study on workplace boredom found that people with higher self-control were more likely to respond with active coping strategies like creating new challenges. Artificial deadlines are just that: a crafted challenge that turns listless repetition into urgency.

2. Competition as fuel

Sometimes I picture Gabe working on the same project. In my mind, we’re racing. He’s faster, more focused, already ahead. That imagined rivalry stirs something primal: I won’t be outdone. It’s childish, maybe, but effective. Where enthusiasm has fled, pride steps in.

Nietzsche’s eternal recurrence sneaks in here. If I had to relive this documentation task endlessly, how would I want it to occur? Would I want to lose each time, or win? The competition is illusory, but the work it summons is real.

Gamification research confirms this. A 2024 mixed-methods study found that when students used a gamified task manager with points, progress bars, and narrative challenges, their self-control measurably increased and procrastination decreased. Competition, even imagined, creates stakes. It reframes dull tasks as battles to be won.

3. Proxy care

When my own care thins out, I borrow someone else’s concerns. Sometimes it’s the PM who needs clear docs to drive adoption. Sometimes it’s the engineer who will get fewer angry Jira tickets if I anticipate the error path.

When I imagine this person, I realize that I’m not writing to fill space. I’m writing to prevent despair. The sentence is a lifeline. Kierkegaard would call this a leap of faith: choosing to invest belief where none is guaranteed.

4. Concern for the future user

This may sound like proxy care, but it’s sharper. Good technical writing moves someone from confusion to clarity. The fatigue tempts me to forget that. When I picture a reader struggling with the product, I’m attentive again.

Choosing to Push the Stone

Camus ends Le Mythe de Sisyphe with an almost scandalous line: “Il faut imaginer Sisyphe heureux.” (One must imagine Sisyphus happy.)

It’s a strange proposal. What kind of happiness could exist in endless repetition? What joy could be found in pushing the same stone, again and again, only to watch it tumble back down?

And yet, the myth is not so distant from the life of a technical writer. We revise tickets that look nearly identical. We polish sentences that will be skimmed. We explain yet another integration workflow, onboarding guide, or API parameter. Push the stone, watch it roll down, return to the base, repeat.

The absurdity is obvious. The question is what you do with it.

When the thrill evaporates, when enthusiasm withdraws like chlorophyll from the leaves, what remains is the chance to decide. You can let the void consume you, or you can lean into the work as an act of defiance.

But how will you do the work? With resentment? With hollow indifference? Or with the quiet, deliberate insistence that clarity is reason enough to move forward?

That choice doesn’t resolve the ennui. It transforms it. And in the rhythm of that persistence, something like meaning flickers back into view.

Not triumphant. Not dramatic. Just steady.

I launched into my standard response. “Documentation bridges the gap between a product and its user. It reduces friction, smooths onboarding, and cuts down on support tickets. Good docs anticipate questions and allow engineers and product managers to focus on higher-value work.”

He nodded politely but looked skeptical. After a pause, he said, “Yeah, I get what you’re saying. But if I were hiring a technical writer, none of that would really strike me. There’s something missing from your answer. Technical writing does something else, but I can’t place what it is.”

That comment stayed with me. What if my go-to explanation has been too narrow? What if the value of documentation isn’t simply functional, but something deeper?

The Explanatory Problem

Most of us in the field explain documentation by listing what it prevents: onboarding pain, endless support tickets, frustrated users. And it’s true — those are real benefits. But they sound defensive, as if documentation’s role is merely to minimize damage. It reduces churn, saves costs, and deflects complaints.

The problem with this framing is that it misses the affirmative value of documentation. If all we can say is that documentation prevents chaos, then we imply that its worth is only negative space, valuable only in the absence of problems. That answer will never inspire confidence, let alone investment.

This negative framing reminds me of another conversation I recently had with a family member. She described friendship in a bizarre way: “Friends keep you from being lonely. They give you someone to talk to when you’re down.” True enough, but inadequate. Friendship is not simply the absence of loneliness. At its best, friendship is formative. It shapes us into who we become.

In the same way, documentation is not just an absence of confusion. At its best, it is formative. It shapes how users see the product, how they experience its purpose, and even how they imagine what they can do with it.

Defining Terms

Let’s pause to name two ideas that will frame the rest of this discussion:

• Utility value: The functional role of documentation in reducing friction, answering questions, and preventing problems.

• Formative value: The deeper role of documentation in shaping perception, guiding imagination, and cultivating confidence in both product and user.

Both matter. But only the second explains why documentation deserves more than a grudging budget line.

Documentation and Self-Imagination

I believe the missing piece my friend was searching for is this: documentation doesn’t just tell people how to use a product. It shapes how they imagine themselves using it. In that sense, documentation has formative value.

When a user encounters a well-crafted guide, he doesn’t just learn how to click the right buttons. He feels oriented. He begins to believe the product can solve his problem and that he is capable of solving it. Documentation, then, is less about friction reduction and more about identity formation. It tells the user: you belong here, and this tool belongs with you.

Cognitive science lends support to this claim. In their 2003 study, Mayer and Moreno show that meaningful learning happens when new information connects to a practical goal and when users see how each step fits into a larger whole. Without this scaffolding, knowledge remains fragmented and is quickly discarded.

Good documentation provides the scaffolding. It doesn’t just prevent confusion. It builds confidence by connecting knowledge to action. In doing so, it shifts the user’s posture from hesitant outsider to capable participant.

Writing Formatively

So how can writers elevate their work beyond utility value and into formative value? A few practices stand out:

• Begin with purpose. Every article should start by naming what the user will gain, not just what buttons they will press. Frame the task in terms of meaningful outcomes.

• Connect steps to identity. Instead of writing “toggle this switch,” explain how the action enables the user to become more effective, secure, or creative.

• Echo the product’s value proposition. Good documentation draws a through line back to the promises made in product marketing, helping users see that the value that sold them on the product continues to unfold as they use it.

• Guide, don’t instruct. Good documentation feels like a knowledgeable companion walking beside the user, not a detached checklist. Anticipate confusion and speak with empathy.

• Show the bigger picture. Remind the user how each piece of knowledge fits into a larger workflow or goal. Context breeds confidence.

Closing

As our dinner plates were cleared, my friend’s question lingered: What’s the real value of documentation? At the time, I stumbled through an answer about onboarding and support tickets. But I wish I had said this:

Documentation is not only a tool for reducing confusion. It is a practice of formation. It helps users imagine themselves as competent, capable, and ready to create. Its value lies not just in what it prevents, but in what it makes possible.

The real value of documentation is that it gives shape to confidence. Like friendship, it doesn’t just keep us from failing. It makes us more fully who we are meant to be.

One misplaced step, one hidden prerequisite, and the whole workflow collapses. The user doesn’t stop to ask if they misunderstood. They blame the instructions. They blame the product. They blame you.

Sequence is invisible when it works, but brutal when it fails. It holds the work together the way gravity holds the world together: quietly, constantly, without applause.

The earliest technical writers didn’t treat order as optional. They knew it was the difference between getting the work done and getting hurt.

When Instructions Were Survival, Not Style

Long before technical writing became a job title, procedure was written because lives and money were at stake.

In the 1st century BCE, Vitruvius produced De Architectura, ten volumes on how to build safely. His prose wasn’t ornamental. It was procedural: list the materials, state the hazards, specify the order. Mix lime wrong and you didn’t just waste time, you burned your hands.

A thousand years later, al-Jazarī, the Muslim engineer, compiled illustrated manuals for ingenious machines: clocks, pumps, automata. His guides were direct: do this, in this sequence. Each step came with a diagram so the gearing never had to be imagined.

By the 16th century, Georgius Agricola’s De Re Metallica pushed the form further. Page after page combined smelters and shafts with procedures, warnings, and roles. He didn’t just show how. He showed what, why, and who. His readers weren’t theorizing about metallurgy. They were waist-deep in mines, surrounded by fire and ore.

The risks look different today, but the principle hasn’t changed. Sequence may no longer burn your hands or collapse a mine, but when it breaks, it still derails the work and erodes trust.

When Sequence Breaks

Picture this. You open a tutorial, eager to get started. Step one: install the package. Step two: configure the settings. Momentum builds. Then halfway through step three, the documentation casually mentions that you need an API key from a different portal.

Momentum stalled.

An oversight like this can appear anywhere in your documentation:

• Prerequisites hidden in the middle of a task

• Environment setup and permissions left unstated

• Steps mirroring the product’s internal architecture instead of the user’s natural workflow

It’s like opening your training app at the gym and finding a surprise superset: resistance work followed by boxing drills. Except your gloves are still at home in the closet. Or your trainer drops in a swim set you never expected, and you didn’t bring a suit.

You don’t just push through. You stall. You scramble. You curse. And then, you wonder why you showed up at all.

It is easy to miss the order of things. To you, the sequence feels obvious. You understand the setup, the permissions, the hidden dependencies. You’ve internalized them.

That’s why good documentation feels like a well-designed workout program. Everything is in its place. The equipment list comes before the first rep.

The sequence isn’t decoration. It’s the thing that makes the work possible.

The ancients understood this. Their pages weren’t polished for style. They were designed for survival. And the patterns they left us still hold.

Lessons From the Ancients

The old writers left us more than dusty manuscripts.

They left patterns worth emulating:

• Treat sequence as a design constraint. Vitruvius assumed his readers could get hurt if they got the order wrong. Write with the same seriousness.

• Pair diagram with action. Agricola didn’t ask miners to picture a smelter from memory. He drew it. Then he explained what to do. Don’t make users imagine your API. Show them a diagram, a call flow, or a screenshot alongside the step.

• Structure for risk. Ask yourself: what happens if the reader misses this step? If the answer is wasted minutes, fine. If the answer is corrupted data, exposed credentials, or a broken build, that step belongs earlier.

• List the tools first. No one publishes a workout plan that hides the barbell until set three. A tutorial that hides prerequisites halfway through isn’t a tutorial. List the required tools before the first step.

Trust Lives in the Order

No one will thank you for putting the prerequisites first. No one will celebrate that every step landed in the right order.

But, they’ll feel it when momentum stalls halfway through a task.

They’ll feel it when the product seems broken because the documentation sent them backward.

Good documentation doesn’t draw attention to itself. It just works. It keeps the reader moving forward, step by step, without friction.

An accurate sequence doesn’t just keep momentum. It solidifies trust.

The short-lived Japanese experiment reveals something larger. Our problem isn’t just long hours or poor policies; it’s an inability to rest. We’ve forgotten what it means to live as if rest had value in itself, and not only production.

The Problem of Constant Production

Modern workers, from coders to professors to technical writers, swim in the same water. Output defines worth. Did you close the ticket? Update the wiki? Answer the Slack message before the ping grew stale? The pressure is constant, and the pace unforgiving. If you can’t keep up, you risk becoming irrelevant. The result is a life lived on the edge of exhaustion.

Documentation itself often bears the marks of this fatigue. Pressed for time, writers settle for shallow drafts, recycling old text and skipping the work of true orientation. The outcome may be technically correct, but it lacks depth and direction. Exhaustion breeds mediocrity. And worse, it breeds the suspicion that this is simply the way life has to be.

But what if it doesn’t?

Sabbath as Resistance

As Moses descends from Mount Sinai, he carries a tablet with these words etched on it (Exodus 20:8-11):

Remember the Sabbath day by keeping it holy. Six days you shall labor and do all your work, but the seventh day is a sabbath to the Lord your God. On it you shall not do any work, neither you, nor your son or daughter, nor your male or female servant, nor your animals, nor any foreigner residing in your towns. For in six days the Lord made the heavens and the earth, the sea, and all that is in them, but he rested on the seventh day. Therefore the Lord blessed the Sabbath day and made it holy.

In our context, the Sabbath can seem like a Puritanical restriction – a stale, legalistic requirement that seems out-of-touch with the modern world. But the Sabbath speaks toward a truth that we can miss without the proper framing.

When the Hebrew Bible introduces the command to rest on the last day of the week, it does so against the backdrop of slavery. The Hebrews had just been liberated from Pharaoh’s economy, a chattel system where their only value was measured in bricks and barley. Under Pharaoh, the Hebrew people existed to produce goods, and their oppressors were endlessly hungry for more.

In this setting, the command to rest shifts from legalistic to subversive. The God of Israel was not a god who demanded constant production from helpless slaves. Rather, YHWH was a God who saw human need, tiredness, and limitation, and respected these realities. YHWH was a God of rest.

During university, I read Walter Brueggemann’s short book titled Sabbath as Resistance, in which he argues that the Sabbath served both as a resistance and an alternative to empire. The command to rest resisted imperial force because it declared that Israel would not be defined by production and consumption, against the will of occupying powers like Egypt, Babylon, or Rome. Even if Caesar wanted business to continue as normal all day, every day, Israel claimed for herself a slower, humane pace that left room for respite. In this way, Sabbath provided an alternative to the empire by carving out space for justice, neighborliness, and mercy in place of tireless, systematic abuse.

The Sabbath was never about some sanctimonious rite of devotion. It was a statement of identity. By resting, Israel declared that they were no longer slaves of Pharaoh but children of God.

In this context, rest is not merely idleness but intentional disengagement from production to recover strength, perspective, and freedom. And that kind of rest has everything to do with us.

Why This Matters for Documentation

Good documentation depends on clarity, perspective, and patience. It requires the writer to step back and see how instructions connect to larger meaning. But this ability is impossible without rest. If we live like Pharaoh’s slaves — producing endlessly with no pause — our words inevitably flatten, and so do we. We become lifeless because we are writing from a place of exhaustion.

Sabbath, or intentional rest, interrupts that cycle. It creates the space where words can breathe. It allows writers to return to their work with sharper questions:

• What problem am I solving?

• How does this task fit into the user’s larger journey?

• Why does this matter?

Without rest, we can easily lose these questions, letting our documents drift toward soullessness.

This insight isn’t only theological; it’s psychological. A 2007 study by Sabine Sonnentag and Charlotte Fritz found that psychological detachment from work during leisure time predicts greater productivity, creativity, and well-being once employees return to their tasks. Rest does not compete with performance — it sustains it.

Practices for the Modern Writer

So what does it mean to practice Sabbath as a technical writer or knowledge worker today? It doesn’t require observing Saturday as sacred. But it does require carving out intentional rhythms of disengagement.

Here are four ways to begin:

• Set real boundaries. Choose times when you will not check Slack, email, or tickets. Protect those times with the seriousness of a meeting.

• Create rituals of renewal. For some, this is a weekly hike. For others, it’s a family meal or reading hour. The form matters less than the intention.

• Work from overflow, not depletion. Begin writing projects after you have given yourself margin to reflect. This is the difference between words that guide and words that merely fill space.

• Model rest for your team. Share openly about your boundaries. Normalize rhythms of disengagement so your peers see that sustainable work includes recovery.

Closing

Japan’s “Premium Friday” campaign failed because it tried to legislate what can only be practiced as a conviction. Sabbath begins not with permission but with belief: that you are more than what you produce. It’s a counter-narrative, an insistence that your worth is not tied to tickets closed, code shipped, or documents published.

Brueggemann is right. Sabbath is both resistance and alternative. It resists the hamster wheel of endless achievement, and it offers the alternative of life built on justice, neighborliness, and rest.

For technical writers — and for anyone trapped in the churn of modernity — the lesson is simple but costly: you were not made for Pharaoh’s storehouses. You were made for rest. And paradoxically, it is this rest that will give your words, and your work, their true power.

Written in memory of Walter Brueggemann (1933-2025), whose work helped sustain my Christian faith through a difficult time.

Subscribe now

Share

The paper is heavy cream stock edged in gold trim. Appetizers, entrées, and desserts are neatly grouped, each set in a clean serif font. Nothing feels out of place. It all feels natural. The menu promises an experience filled with class, quality, and order.

But imagine the same kitchen presenting the same dishes in a different way. There is no cardstock, no gold trim, no tidy rows. Instead, an A-frame stands near the bar, streaked with the dusty residue of chalk. Dishes appear in white handwriting with three already crossed out in red. The whole thing feels temporary, improvised, and alive.

The food has not changed. The structure that delivers it has.

That shift in mood has nothing to do with recipes or ingredients. It comes entirely from the way the choices are arranged in front of you. One structure puts you at ease, another keeps you on your toes, and neither needs to announce itself for you to feel the difference.

Writing works the same way. You can present the same ideas with the same care, but the form you choose shapes what the reader experiences. Sometimes the structure invites them in with clarity. Other times it unsettles them, pulling them into dissonance they can’t quite name.

The difference becomes clearer when you look at the common forms we rely on every day.

Cues Beneath the Form

Think about the kinds of structures we use every day. A checklist template doesn’t just organize steps. It tells the reader this is something they can complete quickly, that progress is visible and measurable. A case study template doesn’t just hold a story. It signals proof, a narrative arc with a problem, a solution, and a victory at the end. A troubleshooting guide doesn’t just list solutions. It creates the sense that recovery is possible, that a path forward exists even when something is broken.

None of this happens by accident. The template is already whispering cues about how to read, what to expect, and how to feel while moving through the material. Most readers never notice it. They just register whether the experience felt clean and clarifying, or confusing and off-key.

However, when the cues are mismatched, the same template that creates clarity can just as easily create confusion.

Trapped in the Wrong Template

Sometimes the failure isn’t an empty section. It’s the right content trapped inside the wrong form.

Imagine trying to explain a multi-step installation process inside a checklist template. The boxes invite someone to race through without pausing, when what they actually need is context, sequencing, and pacing. Or picture a troubleshooting template pressed into service for prerequisites. Instead of feeling prepared, the reader feels like they’ve already broken something. Think about narrative prose used to describe an API route, its parameters, and its responses. What should be crisp, glanceable, and precise turns into a wall of words no one can hold in working memory.

The material might be accurate, even thoughtful. But the template bends it into the wrong shape, and the reader walks away with the wrong experience.

Quiet Precision of Fit

When the structure fits, you hardly notice it at all.

The checklist that guides someone through a series of small, sequential steps becomes almost addictive — each box ticked off, momentum carrying them forward. The troubleshooting guide that stays tightly focused on failure paths gives the reader confidence that no dead end is permanent. The terse table that lays out an API route with its request and response parameters doesn’t draw attention to itself; it simply makes the complex glanceable, the invisible visible.

In each case, the template fades. What remains is the experience: confidence, momentum, relief. The reader doesn’t think, That was a great checklist. They think, I know what to do next.

That kind of fit doesn’t happen by accident. It comes from treating templates less like static forms and more like instruments. A few principles help:

1. Let the content choose the frame. A template should amplify the nature of the material — quick steps into a checklist, complex recovery into a troubleshooting flow, structured data into a table. Don’t force-fit.

2. Keep the spirit, not the letter. Use the template to capture intent, but be willing to bend its format when the reader’s need demands it.

3. Cut the ornamental sections. If a field exists only because the template requires it, remove it. Blank boxes signal bureaucracy, not clarity.

4. Match the mood. Ask what you want the reader to feel — confident, prepared, reassured, curious — and pick the structure that best delivers that mood.

5. Evolve the form. Templates are not sacred. When you see readers consistently struggling or skipping, let the template mutate. The best ones improve with every use.

Experience that Endures

That’s the quiet art of templates. They aren’t there to be admired. They’re there to vanish, to hold the shape of an experience so the content can do its work.

Just like a menu. Heavy cream stock and gold trim create one kind of dinner. A smudged A-frame board creates another. Neither is right or wrong on its own; each succeeds only when it matches the food being served and the mood being set.

Writing is no different. Your reader will never thank you for the template you chose, but they will remember how the experience felt: ordered or chaotic, clear or confusing, effortless or strained.

The food stays the same. The structure decides the meal.

Last week, I was training with my coach and another hurdler. After I ran an interval over the hurdles, my coach gave me some feedback: I needed to keep my trail leg closer to my body. When my trail leg drifted too far from me, it threw my whole body off balance. I made a mental note and prepared for the next rep.

While I got ready, my training partner ran his interval. I saw that his trail leg also drifted a bit far to the right, so I remarked to my coach, “I guess we both have the same problem!”

Coach shook his head. “No. Actually, you don’t,” he replied. “When your trail leg gets too far from you, it throws off your balance. But when James’ trail leg gets away from him, he remains pretty stable.”

Both of us had the same technical issue – a wide trail leg. And yet, this technical flaw had two different effects. For me, it jeopardized my ability to maintain forward momentum off the hurdle. For James, it was just a quirk.

Only I had to fix my trail leg.

Something about this lesson stuck with me after the session. I realized that the best technical writers, like the best coaches, must understand the difference between what is effective and what is efficient.

Effectiveness vs. Efficiency

Let’s define terms:

• Effectiveness is about alignment with an ideal. In sprinting, the elite coach will understand a biomechanical model that maximizes force and speed output, including foot placement, stride length, step frequency, and posture. In writing, the seasoned author will know how to structure content in a way that reflects industry best practices, including a clean information hierarchy, consistent style, and clear progression of thought.

• Efficiency is about adaptability under constraint. In sprinting, the elite coach will recognize how an athlete’s body naturally moves to minimize friction around limits in mobility, explosiveness, or strength. In writing, the seasoned author will recognize an article’s real-world conditions, like tight deadlines, mixed audiences, or unclear specs.

More succinctly, effectiveness is the blueprint, but efficiency is what you build when the ground is uneven.

Now, it’s important to call out that effectiveness and efficiency are not opposites. This isn’t an either-or choice. Rather, these qualities should be complimentary, and the role of the coach or writer is to discern when and where to emphasize the qualities.

The Problem with Technical Models

Technical writers are trained to pursue effectiveness. We seek structure, consistency, and conceptual accuracy. We build documents that align with standards: DITA, ISO/IEC/IEEE 26514, Simplified Technical English., and so on.

This is good. But problems arise when we insist that every document fit the same mold. When we demand rigid correctness without pausing to ask what actually works, we can utterly miss out on a solution for the user, product, or situation.

We can’t always prioritize effectiveness over efficiency.

The truth is that we can’t optimize an article’s structure or content until we understand its constraints. The best instructions address the product that actually exists in front of the reader – and not only in the head of the writer.

Why Balance Matters

In both athletics and writing, efficiency emerges through constraint. The body compensates for weakness by moving in specific ways to protect itself. Likewise, our writing should compensate for timelines, shifting specs, or niche use cases by offering specific guidance. And it’s okay if that guidance doesn’t always look and sound like everything else in our corpus of writing.

In a 2015 study from Muñoz & Van der Meijden in the European Journal of Psychology of Education, researchers found that task performance improved when students were allowed to use their own note-taking systems, rather than being forced into a prescribed format. Their systems weren’t always technically “correct,” and they didn’t always include the same information as other students, but these systems allowed for faster retrieval, stronger comprehension, and higher overall testing. The students’ notes were optimal not because they were effective, but because they were efficient.

The same pattern applies to documentation.

There's a time to enforce the technical model. But there’s also a time to follow the path of least resistance — to observe what’s already working and build clarity around it, even if the result looks slightly off-model.

I recently wrote a support article to help troubleshoot analytics discrepancies. After the first draft of the article, it didn’t feel right to me. It didn’t adhere to our typical outline and standards. So I rewrote it, and then rewrote it again.

Finally, reality hit me. The article accomplished everything it needed to do, and our usual model wasn’t necessary for the article to achieve this end. It was sufficient as a standalone document to help users through a specific kind of data discrepancy and get them on with their lives.

Here, efficiency was better than effectiveness. My job as the writer was to discern which was most appropriate.

The Effective-Efficient Writer

The best writers don’t just write the ideal version of a document. They write the version that the reader can use, the team can support, and the business can sustain.

This doesn’t mean we abandon standards. It means we hold two truths at once:

• A good model matters

• So does the reality of the project in front of you

The effective-efficient writer has the range to adapt for both.

She can write a perfect API reference in Swagger, but she can also triage a support article when an engineer drops a Slack message at 5:15 p.m. She knows how to follow voice and tone guidelines, but she also knows when a hard line or diagram works better than a company-approved metaphor.

She trusts the model, but she trusts her instincts too.

How to Write With Both

So what does it look like to write with both effectiveness and efficiency in mind? Here are three practical shifts:

1. Start with the user’s friction, not your format. Don’t ask “How should this be structured?” before asking “Where is the user getting stuck?”

2. Build to the edge of the constraint. Write the best document you can within the realities of your deadline, audience, and access to source material. Then ask: “What still matters, even if I can’t do this perfectly?”

3. Audit your standards frequently. A style guide should be a tuning fork, not a cage. Revisit what’s working. Adjust what’s not. Let your documents evolve with the body of the team.

Put differently, our articles should be living documents that constantly adjust and readjust to the real-world limitations surrounding them, guided by our technical models.

Closing

Every athlete carries a pattern that’s part ideal and part compensation. Every writer does too.

The most impressive athletes aren’t the ones who match the model exactly. They’re the ones who sprint with economy, rhythm, and force — regardless of whether their stride looks like it came out of a textbook.

To prove my point, Usain Bolt is infamously known for glaring asymmetries in his sprint form, including a 14% difference in ground contact times between his left and right legs. But this didn’t stop him from becoming the fastest human in history.

Likewise, the best technical writers don’t just publish perfect docs. They publish useful ones. They know when to correct the draft, and when to respect what’s working.

Because sometimes, a slightly off-kilter footstrike still gets you across the line first.

***

P.S. We want to give a shoutout to coaches Nathan Taylor of XL Performance and Stu McMillan of Altis for the inspiration behind this article. Thank you both for pouring in to so many athletes.

***

Subscribe now

Share