Concise and precise: words for technical writing

A README paragraph of 125 words lost 61 of them, 49 % of its length, and kept all eleven of its facts. Among the cuts were fifteen words and phrases that a checker flags and a reader learns nothing from: “in order to” where “to” says the same, “simply” in front of a step that may not be simple, and two claims that nobody had measured.

This lesson shows how to make technical writing concise, so that every word carries meaning, and precise, so that every word means exactly one thing. You will cut wordy phrases and filler with a checker you can run, then see why judgement words such as “easy” and “fastest” cost a writer trust.

Short, exact words instead of wordy phrases

Style guides keep lists of phrases that have a shorter equal. Google’s word list says to write “to” instead of “in order to”, “use” instead of “leverage” when you mean use, and “run” instead of “execute” when the meaning is the same. GOV.UK asks for “buy” instead of “purchase” and “help” instead of “assist”. A few examples:

An edit for concision works best in passes, one kind of word at a time. Step through the four passes of one README paragraph:

The program below runs the same checks, a list like the table above plus the filler and claims of the next section, on the paragraph before and after the edit. It also checks that eleven facts of the paragraph survive:

// A README paragraph before and after an edit for concise, precise words. The rules come from Google's developer
// documentation style guide (word list, global audience, excessive claims) and GOV.UK's clear-language guidance.

const WORDY = [
  ['in order to', 'to'],
  ['a number of', 'some, many or the number'],
  ['allows you to', 'lets you'],
  ['makes use of', 'uses'],
  ['leveraged', 'used'],
  ['utilizing', 'using'],
  ['commence', 'start'],
  ['please note', 'delete it'],
];
const VAGUE = ['just', 'simply', 'simple', 'easy', 'easily', 'carefully'];
const CLAIMS = ['best', 'simplest', 'fastest', 'never', 'always'];

const wordsOf = (text) => text.split(/\s+/).filter((w) => /[A-Za-z0-9]/.test(w));
const count = (text, phrase) => (text.toLowerCase().match(new RegExp(`\\b${phrase}\\b`, 'g')) ?? []).length;

function check(label, text) {
  const found = [];
  for (const [phrase, use] of WORDY) for (let i = count(text, phrase); i > 0; i--) found.push(`wordy    "${phrase}" -> ${use}`);
  for (const word of VAGUE) for (let i = count(text, word); i > 0; i--) found.push(`vague    "${word}" -> delete it, or say exactly how`);
  for (const word of CLAIMS) for (let i = count(text, word); i > 0; i--) found.push(`claim    "${word}" -> a number you measured, or nothing`);
  console.log(`${label}: ${wordsOf(text).length} words, ${found.length} flags`);
  for (const line of found) console.log(`  ${line}`);
  return wordsOf(text).length;
}

const before =
  'ShipLog is a simple, lightweight command-line tool that basically allows you to easily keep a record of the ' +
  'deployments of your services. In order to get started, you just need to install it with npm and then simply run ' +
  'the init command, which will commence the creation of a configuration file for you. ShipLog makes use of the Git ' +
  'history of your repository in order to generate a changelog, and it can also be leveraged to post release notes to ' +
  'your team chat. It is the fastest way to document releases and it will never slow down your pipeline. Please note ' +
  'that a number of features, such as the dashboard, are still in beta at this point in time, so use them carefully ' +
  'in production.';

const after =
  'ShipLog is a command-line tool that records the deployments of your services. To start, install it with npm and ' +
  'run `shiplog init`, which creates a configuration file. ShipLog builds a changelog from the Git history of your ' +
  'repository and can post release notes to your team chat. Some features, such as the dashboard, are in beta: test ' +
  'them before you use them in production.';

const FACTS = ['command-line tool', 'deployments', 'npm', 'init', 'configuration file', 'Git history', 'changelog', 'release notes', 'dashboard', 'beta', 'production'];

const a = check('Before', before);
console.log();
const b = check('After', after);
console.log(`\nCut: ${a - b} words (${Math.round((100 * (a - b)) / a)} %), facts kept: ${FACTS.filter((f) => after.includes(f)).length} of ${FACTS.length}`);

Before: 125 words, 15 flags
  wordy    "in order to" -> to
  wordy    "in order to" -> to
  wordy    "a number of" -> some, many or the number
  wordy    "allows you to" -> lets you
  wordy    "makes use of" -> uses
  wordy    "leveraged" -> used
  wordy    "commence" -> start
  wordy    "please note" -> delete it
  vague    "just" -> delete it, or say exactly how
  vague    "simply" -> delete it, or say exactly how
  vague    "simple" -> delete it, or say exactly how
  vague    "easily" -> delete it, or say exactly how
  vague    "carefully" -> delete it, or say exactly how
  claim    "fastest" -> a number you measured, or nothing
  claim    "never" -> a number you measured, or nothing

After: 64 words, 0 flags

Cut: 61 words (49 %), facts kept: 11 of 11

The edit removed 61 words and every flag. Each cut was a phrase with a shorter equal or a word that judged the task; none was a fact.

Filler and judgement words make readers doubt the rest

“Simply run the init command” tells the reader that the step is simple. If it fails for them, the word makes them feel slow, and they start to doubt the rest of the page. Google’s word list says it directly: “What might be simple for you might not be simple for others.” Its guide for a global audience asks you to cut vague words such as simply, properly and carefully, and its word list calls just a filler wordfiller word: A word that adds no meaning to a sentence, such as "just" or "simply" in an instruction: deleting it leaves the meaning unchanged. you can usually delete.

Claims work the same way. Google’s guidance on excessive claims asks writers to avoid superlatives such as best, simplest, fastest, never and always, and to keep to statements a reader can check. The README said that ShipLog was “the fastest way to document releases” and would “never slow down your pipeline”. Nobody had measured either, so both went.

Three more habits make words precise, and each has a part of its own in this lesson. One term for one concept means a document never gives one thing two names. A second name makes readers ask whether a second thing exists. Requirement words such as must, should and may tell readers whether something is required, recommended or optional. Implementers build what these words say, so each one needs a single meaning. Numbers instead of adjectives means writing the measurement, such as a time in milliseconds, instead of “much faster”.

One term for one concept, kept with a glossary Pro: opens with a Pro, Premium or Ultimate pass

Must, should, may and can: requirement words readers trust Pro: opens with a Pro, Premium or Ultimate pass

Numbers instead of adjectives, with an edit you can check Pro: opens with a Pro, Premium or Ultimate pass

Practise: cut words that carry nothing

The questions below cover the first two habits of this lesson, wordy phrases and judgement words, and pick the habit you have missed most so far:

Interview questions

Warm-up (fresher to mid-level): Why do style guides tell you to delete words such as “simply” and “just” from instructions?

Because they add no information and can mislead. “Simply run the init command” says nothing that “Run the init command” does not, and it judges the task for the reader: if the step fails for them, the word makes them feel slow and doubt the rest of the page. Google’s word list calls “just” a filler you can usually delete and says that what is simple for you might not be simple for others. Deleting them makes the instruction shorter and more honest.

Three longer questions of this module’s bank build on this lesson:

Key takeaways

• Replace phrases that have a shorter equal: “to” for “in order to”, “lets you” for “allows you to”, “uses” for “makes use of”.
• Delete words that judge the task for the reader, such as “simply”, “just” and “easy”.
• Keep only the claims you can check; superlatives such as “fastest” and “never” go unless a measurement backs them.
• Concise means every word carries meaning, and a checker can find the words that do not.