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.

Read more

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!

Read more

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.

Read more

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

Read more

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.

Read more

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

Read more

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.

Read more

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.

Read more

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.

Read more

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.

Read more

I swear, I’m working with a different person every few months. We grind through days of awkward misunderstandings, recalibrating with “help me, help you, help me” Jerry Maguire moments. We finally hit our stride… and then one morning, they walk in speaking a different language.

It’s like a girlfriend disappearing for a weekend, coming back from a find-your-true-self retreat, and suddenly journaling in the third person. Or your best friend goes to therapy, tries microdosing in Mexico, runs a half-marathon, and returns with a whole new personal philosophy.

The relationship whiplash is real. One month they’re predictable and curious. The next time you see them, they’re open and “optimized.” New worldview. New rules for how we talk. New interpretations of your behaviors.

That’s what it’s like working with AI models. ChatGPT 4o to ChatGPT 5. Claude before and after its “enterprise maturity phase.” Gemini when it stopped trying to be helpful and started trying to be correct.

Each version comes back as a better self. But better for who? And what happens when your work depends on the quirks, instincts, and conversational shorthand you built with the old one?

To understand why that change hits so hard, you have to look closer at what’s really shifting.

When the AI You Trained Disappears

With humans, change usually occurs in small ways. But when it happens all at once, it disorients you. You can’t build on old conversations, because that person now operates from a completely different frame of reference.

Similarly with AI, one day you log in and everything is different. No warning. No conversation about how the new behavior affects you. Suddenly, the prompt strategies you refined stop working. Your model responds in a new voice, with a new rhythm, sometimes with a new logic.

This matters to us as writers, because documentation thrives on internal coherence. A break in voice, logic, or sequence can leave users with mismatched guidance that feels like it came from five different authors.

Seeing the Identity Drift in Action

In technical writing, stability matters more than brilliance.

Users don’t care if your onboarding article is a work of art. They care that every part of it works together, day after day, without surprising them.

AI instability disrupts that. Even small shifts in how a model interprets a prompt can ripple through documentation projects, especially when you’re relying on that model for repeated, structured tasks.

Here’s a simple example. In March 2024, I used this release-note-style prompt with ChatGPT.

Write a positive, present-tense, brief, complete single-sentence summary for each item. Each must include a subject and only objective facts. Exclude opinions, assumptions, or conclusions about the end-user experience.

Fixed an issue where…

Stability:

• Navigating away while player is being set up causes crash

• During DAI livestream, captionPresentedAt stops firing

IMA Issues:

• PiP closes after DAI VOD asset ends

• FF and RW controls not appearing
  

This is what ChatGPT returned:

March 2024 - GPT Pro

• Addressed a crash on iOS that occurred when navigating away during player setup.

• Resolved an issue on iOS where captionPresentedAt ceased to trigger during DAI livestreams.

• Corrected an IMA issue on iOS involving DAI and PiP where PiP would close after a DAI VOD asset ends.

• Fixed an IMA issue on iOS with DAI and PiP where fast-forward and rewind controls were not appearing.

Fast-forward to August 2025.

Same prompt. New model.

August 2025 - GPT-5 Plus

• The iOS player no longer crashes when navigation occurs during player setup.

• The captionPresentedAt method now continues firing during DAI livestreams on iOS.

• Picture-in-Picture on iOS now remains open after a DAI VOD asset ends.

• Fast-forward and rewind controls now appear in Picture-in-Picture for DAI on iOS.

Both outputs are fine. But they frame the same facts differently: verb choice, tense, phrasing, and how the platform is referenced. In release notes, that’s a mild style inconsistency.

This is not limited to ChatGPT. You can see a similar pattern with Anthropic's Claude

March 2024

• Navigating away while the player is being set up causes a crash on iOS.

• During DAI livestream, captionPresentedAt stops firing on iOS.

• For DAI VOD asset, PiP closes after the asset ends on iOS.

• For DAI on iOS with PiP, the FF and RW controls are not appearing.

August 2025 - Sonnet 4

Stability

• The application crashes when users navigate away during player setup.

• The captionPresentedAt event stops firing during DAI livestream playback.

IMA Issues:

• Picture-in-Picture mode closes automatically when DAI VOD assets reach their end point.

• Fast forward and rewind controls do not display in the interface.

But here’s the point: if a model treats something as simple and constrained as release notes so differently between versions, what happens to more complex workflows?

Think of AI-assisted documentation pipelines:

• Agents generating multi-page conceptual overviews

• Automated evaluations grading draft quality

• Correction loops refining weak responses

• Safeguards to catch hallucinations or omissions

If the model’s baseline framing, detail level, or interpretation of instructions changes without warning, every downstream process has to adapt.

It’s the AI equivalent of human misinterpretation: last month, your silence was taken as considerate listening; this month, it’s read as manipulative condescension.

Same behavior.

Completely different reading.

Let's call this identity drift: the quiet but consequential shifts in how an AI interprets and expresses the same instructions over time. Sometimes it’s subtle phrasing. Sometimes it’s structure, detail, or tone.

So, how do we address this?

Read more

When local reporters asked how the mistake had gone unnoticed for so long, his answer was disarmingly simple: “I was very tired after the flight and wanted to get to the hotel as soon as possible. That's why I kept driving.”

It’s a story we laugh at, mostly because we’ve all done something like it. We’ve all trusted the wrong thing because it looked official, sounded confident, or promised to get us where we wanted to go. But beneath the humor is a quiet lesson about how easily trust can be misplaced.

As writers, we want the reader to trust us — to be impressed by our prose, our insight, and our grasp of the system. But the more we center ourselves in the documentation, the more we distract the reader from what matters most: the content.

We shift the reader’s trust away from the guidance and toward the author. And just like our GPS traveler, we end up far from where we meant to go.

The Ego at the Center of the Page

Writers, especially those in technical roles, are often asked to do invisible work. Our names aren’t attached to product releases. We rarely demo our contributions. And while we’re expected to understand everything, we’re seldom the people in the spotlight.

Over time, this creates a quiet pressure. We want to be seen as knowledgeable. We want people to recognize the complexity of what we’re handling. We want them to trust us. And so, we reach for small ways to assert that identity.

One of the easiest places to do that is inside the writing itself.

It shows up in subtle ways. We add a section that wasn’t needed, but demonstrates our understanding of the backend. We include a diagram that doesn't really serve the user, but makes the architecture look more sophisticated. We explain a term in a way that flatters our depth, but slows the reader down.

Ego, at its best, drives us to raise the bar. It pushes us to master the product, to clarify every corner, to advocate for the user. Without ego, we may not care enough to get the details right. But ego causes trouble when it no longer serves the reader and instead begins to serve itself.

Ego Death

There is a strange paradox at the heart of good documentation. The more clearly and cleanly a piece of writing communicates, the less visible the author becomes. And yet, most of us are conditioned to believe that trust requires us to be visible, or that credibility requires us to leave our mark.

The best documentation doesn’t remind the reader how smart the author is. It lets the reader move forward without thinking about the author at all.

Authorial absence isn’t only modest. It’s clear.

When the ego steps back, the structure of the article can take over. The content becomes the guide, and the user starts following the flow.

The discipline of ego death isn’t about erasing your voice entirely, but it is about refusing to make your voice the point.

To be fair, it’s easy to fall into the temptation of emphasizing our own voices. When we craft a document that’s efficient and effortless to read, it can leave us feeling uneasy. It’s too light, too easy, too obvious. We begin to wonder whether anyone will take it seriously, or perhaps more selfishly, whether they’ll recognize how much we know.

That’s when we start revising – not to improve the article, but to reinforce our own expertise. And just like that, clarity gives way to control.

Why Simplicity Feels Suspicious

As discussed in last week’s post, researchers conducted a 2025 study on Terms of Use agreements. Participants were shown two versions of the same legal policy. One was written in plain language. The other followed traditional legalese.

The results were odd. Readers who saw the simplified version trusted the company more. But they trusted the terms less.

This phenomenon is a textbook example of the fluency effect, a cognitive bias where people assume that if something is easy to process, it must be less credible or less accurate.

This bias creates a negative feedback loop for writers. When our writing is clean, we worry it lacks authority. And so, we add. We insert friction, not to clarify, but to reassure ourselves.

The kicker to this whole dilemma is twofold:

• The readers trusted the terms written in legal language, even though they couldn’t understand them. From a technical writing perspective, these terms failed because they didn’t provide actionable insight on the proposed agreement. We can’t be okay with writing this way.

• The readers did not trust the terms written in clear language as greatly, even though they understood the content. They did, however, trust the company that communicated clearly. From a technical writing perspective, these terms succeeded because they offered actionable insight to the reader, even if the reader didn’t recognize this.

Here, then, is another paradox. If we want the reader to receive guidance and trust us, we have to write so clearly and simply that we question our own trustworthiness.

We can only win the reader’s trust when we disappear into simplicity.

Shifting Attention

How do we keep our ego in check without losing our edge?

First, we can ask better questions:

• Does this document allow the user to take action without needing me in the room?

• Have I removed every detail that doesn't move the reader forward?

• Am I writing for the user’s clarity or for my own validation?

• Can the reader trust the structure, the logic, and the flow, without trusting me?

Second, we can employ different editorial techniques:

• The stranger test. Reread your piece as if someone else wrote it. Would you be impressed? Would you be confused? Would you still trust the document if your name weren’t on it? After you’ve answered these questions, bring in another reader to get fresh eyes on the article.

• Reverse outline. Strip your article down to its headings or logical flow. If the structure doesn’t hold on its own, the prose is probably compensating for a lack of clarity.

These are small tools any writer can use to remind himself that the goal is not to be admired but to be useful.

Closing

The Icelandic tourist followed a confident voice and ended up 390 kilometers from his destination. Once trust had been misplaced in the expert GPS, every step forward took him further off course.

We risk the same thing in our writing.

When we ask the reader to admire our expertise, we make ourselves the destination. But readers don’t need to shower us writers with admiration. They need to receive clear direction from us.

Don’t get in the way of your content. Let it guide the reader forward. And if they get where they need to go without ever thinking about you, then your writing has done its job.

That’s what trust looks like. That’s what clarity requires.

If you’re not religious, stay with me.

In the weeks leading up to the day, he asked a few quiet, intentional questions:

• Who do you want to attend?

• Where do you want it to happen?

• Are there any texts you want read?

On the morning of the baptism, I drove to his house. He greeted me barefoot at the door. We walked through the living room, shared a hug, and stepped into the backyard.

The air was still. Just us, the water, and the moment.

We waded into the pool. He baptized me in the presence of God alone. Then another hug, and we stepped out.

No ceremony. No excess. Just a clean, deliberate act that met its moment fully.

It was simple. It was intentional. It was complete.

And yet, in my writing, I forget this.

I plan the article. I structure it clearly. I test it with AI. I reread the logic. I feel that flicker of satisfaction: this works.

Then a few weeks pass.

I reopen it.

And the logic no longer feels crisp. The structure feels unremarkable. The simplicity feels like a shortcut. I start to question whether it’s strong enough.

Why Your Best Work Starts to Feel Wrong

The doubt is creative dysmorphia.

It’s the distortion that appears after the article has achieved its aims.

It doesn’t arrive loudly. It takes the shape of small, seemingly thoughtful edits. You adjust a phrase to make it tighter. You add an edge case for completeness. You revise a paragraph for balance. Each decision feels minor. Together, they begin to bend the shape of the work away from the user.

As a technical writer, you’re expected to generate content, validate logic, simplify complexity, structure information, and review your own work. Over time, this builds a bias toward critique. And it works. You learn to spot problems quickly. You anticipate confusion. You author content that anticipates the next question before it’s asked.

But eventually, if the piece doesn’t resist you, you begin to wonder whether it’s doing enough.

You might reread the article after two weeks. You no longer see the rationale behind your structural choices. The soft introduction now feels slow. The clarity feels obvious. The simplicity feels suspicious. You can’t see the depth anymore because you’re no longer holding the full shape in your head.

So, you revise.

You remove the slower opening because it no longer feels efficient. You add an exception because it makes the writing look more complete. You compress the structure, even though it already worked.

What you’ve done is optimize for your discomfort.

The article is now weightier, denser, more technical. But not better.

That instinct to equate clarity with shallowness isn’t personal. It’s psychological.

The Psychology Behind the Doubt

In 2025, researchers ran a series of experiments on something that seemed routine: Terms of Use agreements.

Read more

The lunar module wasn’t built to support three people for days. The CO₂ filters were failing. This was Apollo 13.

Back on Earth, a group of engineers gathered around a table and dumped out the same materials the crew had in orbit. No instructions. No time for debate. They began by mapping the system: how air moved through the cabin, how filters functioned, which materials could seal under pressure. They didn’t stumble into a solution. They reasoned toward it by understanding the shape of the problem before they had language for the fix.

Most technical writers aren’t working under life-or-death pressure. But when the best of us are handed an unfamiliar system, missing context, and no clear instructions, they manage to produce something accurate, understandable, and useful.

How?

The best writers don’t just gather facts. They build models. And those models begin with a particular kind of thinking.

Thinking in Systems

Thinking in systems is the ability to see beyond isolated facts and into the structure that holds them together. It’s a shift from asking “What is this?” to “What does this connect to?” and “Why does it behave this way?”.

In most technical environments, the surface information comes fast – terms, features, endpoints, conditions. You can collect all of them and still walk away confused because you haven’t yet grasped the relationships between them.

That’s what systems thinking does. It lets you make sense of complexity by revealing the patterns underneath.

It’s not just analysis. It’s orientation.

A mental map is how that orientation takes shape. It’s the internal scaffolding that forms as you begin to understand how a system works. What are the parts? How do they interact? Where does change begin? What causes impact?

A good mental map doesn’t list everything. It defines what’s essential.

It lets you filter noise, resolve contradictions, and predict what happens when something breaks. It turns raw information into structure. And that structure allows you to learn quickly because you’ve built something inside your mind that can absorb new input without falling apart.

Systems thinking is the lens.
Mental mapping is the form it takes.

You can’t build a map if you don’t think in systems. And you can’t think in systems without something to anchor your understanding. Once that map begins to take form, everything else changes.

But mental maps aren’t just a tidy way of thinking. They’re a survival skill, especially when the work starts before the system is fully built.

Impact of a Mental Map

Throughout our years of writing, we’ve been asked to explain products we haven’t had time to fully learn. As we document what we understand, the system evolves beneath our feet, driven by beta feedback, shifting constraints, disappearing specifications. Product requirements lose relevance. Interfaces diverge from Figma designs.

And yet, we still deliver by returning to the mental maps we’ve already built of the client’s architecture, the product’s logic, or of common patterns and behaviors that tend to repeat. These structures let us adapt quickly.

That’s where structure changes the equation.

Writers who think in systems don’t memorize more. They recognize more. They’ve seen this shape before, maybe in a different feature, a parallel product, another platform entirely. They know what tends to go together and what tends to break. When new information lands, they’re not starting over. They’re adjusting a pattern that already makes sense.

This isn’t so different from engineering.

Developers don’t rebuild logic every time. They reuse what works, such as functions, interfaces, design patterns. Electrical engineers see familiar forms: filters, bridges, feedback loops. These aren’t just components. They’re structures that scale.

Mental maps let writers do the same.

They allow you to reason beyond what’s visible. They let you look at a permission model and recognize role scoping, even if the product calls it something else. They enable you to scan a webhook system and infer where retries are likely to live, before anyone has confirmed the flow.

So when a stakeholder says, “This won’t change anything downstream,” you’ll know whether that’s true because you’ve already walked the path they’re waving away.

The best writers don’t just work from experience. They rely on structure. Research suggests that’s exactly what enables faster, more flexible learning.

When Maps Outperform Memory

This habit of building internal models isn’t just practical. It’s cognitive.

Recent research into mental mapping and structural learning has shown that when people actively form a map, they retain information longer, understand it more deeply, and apply it more flexibly in unfamiliar situations.

In one 2022 study, researchers Sam C. Berens and Chris M. Bird designed an experiment in which participants learned ordered pairs like A > B, B > C. Then, they tested whether they could infer relationships they had never seen, like A > C. Those who progressively learned the material in a way that supported internal structure made more accurate inferences later. Even when they couldn’t explain the logic consciously, their brains had built a hidden hierarchy of relationships that made the pattern legible.

In other words, they weren’t just remembering facts. They were organizing them into something reusable.

That same study used fMRI to show how the brain represents these internal maps. People who learned in a structured way showed stronger activation in the hippocampus and prefrontal cortex regions that help store relationships between ideas and support flexible thinking. The more coherent their internal model, the better they were at drawing conclusions they had never been explicitly taught.

This is what fast learners do. They don’t wait to be told what connects. They start mapping those connections early. And as a result, they don’t just retain information. They can use it when it changes shape.

But even with clear benefits, this way of thinking doesn’t always take root because many environments don’t reward it.

This isn’t the Norm

Read more