Last spring a small operations team inherited a service from a group that had been reorganised away. The handover document was eleven pages long, and none of the new team could say, after reading it, how to restart the service when it stalled. The words were all correct. They were also all inside a private dialect that had walked out of the building with the previous owners. The new team spent a week learning by breaking things, and then one of them said, “Let’s write down what we learned in plain words, so the next team does not suffer.”
That sentence started a habit, and the habit produced a list of questions that kept coming up. This post answers them one by one, in the order the team met them. If you maintain any technical documentation, you will probably recognise a few.
Why does technical writing slip into jargon in the first place?
Mostly because of familiarity. After a year with a system, the words you use to describe it stop sounding like words. They sound like facts. You forget that “the replica” or “the hot path” was a phrase you once had to ask about. Time pressure adds to this: shorthand is faster to type than explanation, and the author is rarely the one who suffers later.
Nobody sets out to write something unreadable. The fog builds up, sentence by sentence, from perfectly reasonable shortcuts.
Is jargon always bad?
Not at all. A team that tries to banish every technical term will only create new confusion. A precise word that everyone already shares saves effort. The trouble begins when a term is used with people who may not share it: new joiners, teams elsewhere in the company, or the colleague who covers on-call over a holiday.
A fair rule is to use the technical term, but explain it in a few words the first time. “The replica, a second copy of the database that takes over if the main one fails” costs eight extra words and saves a message to ask what the replica is.
How do we spot jargon in our own writing?
You cannot easily see your own blind spots, so borrow another pair of eyes. The team in our story gave each new joiner a highlighter and a printed page on their first day. Anything they did not understand got a stripe of colour. By the end of the week the pages were striped, and the stripes showed exactly which words needed a plain partner.
If no new joiner is around, pretend a neighbour who sells fabric for a living is listening, and say the paragraph to them. Wherever you wince or start rushing, jargon is probably hiding.
What does a plain-words rewrite look like in practice?
Here is a real-sounding step from the old document: “In the event of a stalled consumer, initiate a graceful drain and re-queue unacknowledged messages prior to restart.” The team’s rewrite read: “If the service that picks up messages stops responding, first let it finish what it is doing. Then put any unfinished messages back in line and restart it.”
The facts are unchanged. The second version simply says what each part is: the consumer became “the service that picks up messages,” draining became “let it finish,” and re-queuing became “put them back in line.” A person who has never restarted the service can follow it, and a person who has will recognise every step.
Can a plain rewrite go too far?
It can, if the writer starts trimming facts along with the fog. The team hit this once: an editor shortened a step to “restart the service,” dropping the warning that the restart takes about a minute and drops live connections. A colleague caught it during a read-through. The lesson they wrote on the whiteboard was simple: cut the fancy words, never the warnings or the numbers that people rely on. A rewrite is finished when a stranger can follow it and the original author still agrees it is true.
They also found that reading both versions together was a good final test. If the original author reads the plain version and says, “yes, that is exactly what I meant, only clearer,” the rewrite is safe to publish.
Will plain writing make us look less professional?
The team worried about this at first, and then watched what happened in practice. The managers who read the new notes said they finally understood what the group did. The engineers on other teams started copying the layout. Professionalism turned out to be about being reliable and clear, and plain wording delivered both.
The same thread runs through this site’s article on how habits and working culture change inside a DevOps team, which makes the same point from the management side: changes stick when people understand them.
How long does it take to rewrite a document?
Less than most people fear. The team set a rule of fifteen minutes per page for a first pass. They did not try to perfect everything. They tackled the pages people used most, namely the restart steps, the contact roles and the “what does this alarm mean” list, and left deep technical appendices alone.
Plain-language edits are also quicker when the old document is clear about the facts. Most of the time the work is not discovering what to say but replacing the label you wrote with the idea behind it.
What about terms we really cannot avoid?
Keep them, and give each one a home. The team added a short “words you will meet” box at the bottom of each page, with two lines per term. This is different from a giant glossary at the back of a manual; the box sat on the same page as the procedure, so readers did not have to flip anywhere.
If a term needs more than two lines, it probably deserves its own short page, and the procedure can simply point to it.
Does this help with risk, not only with comfort?
Yes, and this surprised the team. When a step in a runbook is vague, people improvise, and improvisation under stress is how small problems become large ones. Clear instructions leave less room for creative guessing at three in the morning. The article on managing risk so that software releases stay dependable and secure touches on this connection between clarity and reliability from a wider angle.
Is there anything outside engineering we can learn from?
Plenty. Any public-facing website has to be understood by strangers in seconds. A site like DelhiOrbit, an events website for the city of Delhi that includes a blog, venue pages and a community forum, labels its sections in everyday words, so a visitor looking for a weekend outing never needs a manual. The team started noticing the same instinct in transport signs, pharmacy labels and bank forms, and began asking, “Would a stranger understand this?” of their own pages.
What is the smallest first step?
Pick one page that gets read in a crisis: the restart instructions, the escalation list, the explanation of the loudest alarm. Print it. Give it to someone from a different team and a highlighter. Rewrite every striped phrase in everyday words. That single page will tell you whether the habit is worth spreading.
The team in the story ended the quarter with fifteen rewritten pages and one new rule: no page goes live until a colleague who did not write it has read it aloud without stopping to ask what a word means. The next group that inherited the service restarted it on their first morning, without a single message to the old owners, and that small silence was the best review the documents ever received.









