Concision

Based on the chapter in Williams & Bizup of the same name.

Another Review

Let's apply what we have learned to another example:

The Spring Framework provides a comprehensive programming and configuration model for modern Java-based enterprise applications — on any kind of deployment platform. Spring Framework

Actions, characters, emphasis, …

Another Review

Maybe better as:

The Spring Framework helps you write modern Java-based enterprise applications on any deployment platform, by providing a comprehensive programming and configuration model.

Familiar topic: Spring helps you write Java things.

New emphasised info: programming and configuration model.

Another Review

But why not this?

Spring helps you structure Java applications.

Another Review

Compare the content of the original.

The Spring Framework provides a comprehensive programming and configuration model for modern Java-based enterprise applications — on any kind of deployment platform. Spring Framework

These became Spring, helps you structure, Java applications, and .

Some meaning was dropped, but was it important? (The answer will depend on the context.)

Concision

People often write more than they need to. There are many reasons, but some big ones:

• lack of though about what's important
• failure to organize material
• bad habits
• sloppy wording, unfocused sentences
• page/word count requirements

Especially with technical writing, there's value in being concise (brief, terse, etc).

Concision

So should this…

It was the best of times, it was the worst of times.

be turned into this?

Times it was:

1. best of,
2. worst of.

Concision

First think about your audience and the content they need.

• What do they already know?
• What do they care about?
• What do they need to learn here?

Don't include ideas just because you can think of them.

Concision

We'll worry here about sentence- and paragraph-level concerns.

But don't forget to think about concision in content when you're writing actual documents.

Concision Diagnosis

Let's look at a few things that you can do to get rid of extra words…

Meaningless Words

Delete meaningless words. There are several words that often aren't doing much in a sentence: they're just verbal tics.

e.g actually, really, various, generally, basically.

Have a look to see if these are really doing anything important. If they actually aren't, delete them.

Meaningless Words

Oops.

Have a look to see if these are really doing anything important. If they actually aren't, delete them.

That could have been:

Have a look to see if these are doing anything important. If they aren't, delete them.

Or even:

If these aren't doing anything important, delete them.

Meaningless Words

Another example:

If you are really a product of the materialistic universe, how is it you don't feel at home there? C.S. Lewis

If you are a product of the materialistic universe, why don't you feel at home there?

(Because C.S. Lewis wasn't a technical writer.)

Meaningless Words

This advise can contradict the emphasis advice to shift important stuff to the right:

A primary key uniquely specifies a tuple within a table.Wikipedia, “Relational database”

There is a primary key to uniquely specify a tuple within a table.

… which is why this emphasis trick should be done carefully and occasionally.

Delete Implied

Delete what readers can infer. People often word a thought by saying the same thing twice. In particular, redundant modifiers that aren't really adding.

Some examples:

• the past history → the history
• final outcome → outcome
• free gift → gift
• consensus of opinion → consensus

Delete Implied

Or in the CS world:

• running time complexity → time complexity → complexity (depending on context)
• compiler optimization opportunity → optimization opportunity
• requirements document → requirements

Delete Implied

Also look for redundant categories which are implied by the word itself.

The province manages the educational system.

The province manages education.

Delete Implied

Some others:

• nation of Canada → Canada
• during that period of time → during that period or during that time
• the Python programming language → the Python language → Python (depending on audience)

Delete Implied

Imaging someone trying to learn the rules of playing the game of chess. Williams & Bizup, 11th ed, p. 129

But learn implies that you're trying. We know chess is a game.

Imagine someone learning the rules of chess.

We could try this, but learning chess ≫ learning the rules of chess. This edit shifts the content:

Imagine someone learning chess.

Delete Implied

This was the basis of removing on any kind of deployment platform from the Java Spring example. That's a banner feature of the Java language, so Java should imply any platform to a tech-saavy reader.

Replace Phrases

Replace a phrase with a word. Sometimes the right vocabulary can save a bunch of words be concise.

Before you do anything else, design your workflow.

First, design your workflow.

You have to think of the word.

Replace Phrases

• update your writing → edit
• in the event that → if
• despite the fact that → even though
• person that makes hats → milliner
• add to the top of the stack → push
• convert the data structure to bytes → serialize the data structure

You have to know the right word, and so do your readers.

Negative to Affirmative

Change negatives to affirmatives. Sentences that negate the main action are generally less concise, and a little harder to figure out.

Do not write in the negative.

Write in the affirmative.

Negative to Affirmative

There are many cases where there's a way to express the negation.

• not permit → deny
• not often → rarely
• not include → omit

Negative to Affirmative

Some words have an inherently-negated meaning and should get the same treatment.

This will prevent continuation of the project.

This will cause halting the project.

This will halt the project.

Negative to Affirmative

Some examples:

• prevent ↝ allow, cause
• without ↝ with
• unless ↝ because
• reject ↝ approve, permit
• contradict ↝ agree, corroborate

Of course, you need to negate the sentence around these changes. That won't always be nicer.

Negative to Affirmative

This particularly helps when you have a double-negative in a sentence.

It will not be possible to refuse entry.

We must allow entry.

Negative to Affirmative

As always, this rule should be applied with some thought. I don't feel like these are synonymous (or equally clear):

Your package should not include the functionality described above. A2 draft spec

Your package should omit the functionality described above.

The algorithm will not halt.

The algorithm will continue.

Adjectives and Adverbs

Many authors are tempted to sprinkle adjectives and adverbs everywhere. Remove adjectives and adverbs if they aren't important to the meaning of the sentence.

This is an extremely important topic which will have long-lasting implications in your future career.

This is an important topic which will have implications in your career.

Adjectives and Adverbs

Don't remove them if they're actually doing something useful.

The old method for solving the problem was to exhaustively consider every possibility.

The method for solving the problem was to consider every possibility.

The old method for solving the problem was to consider every possibility.

Adjectives and Adverbs

As usual, some balance is required. A complete lack of adjectives/adverbs can leave your writing flat.

The School of Computing Science follows SFU's long-standing tradition of excellence in teaching and research. Many graduates apply their broad-based skills as entrepreneurs and business leaders in their exciting fields of interest.

The School of Computing Science follows SFU's tradition of excellence in teaching and research. … Many graduates apply their broad-based skills as entrepreneurs and business leaders in their field. About SFU CS

The School of Computing Science follows SFU's tradition of teaching and research. Many graduates apply their skills as entrepreneurs and business leaders.

Metadiscourse

Metadiscourse: writing that talks about what the writing is doing. e.g. we first consider, to summarize, I believe, note that.

Once again, too common in academic writing, and an ugly way to bump up the word count without saying anything.

The last point I would like to make is that in regard to men-women relationships, it is important to keep in mind that the greatest changes have occurred in how they work together. Williams & Bizup, 11th ed, p. 133

Metadiscourse

Little of that text is about the actual topic:

The last point I would like to make is that in regard to men-women relationships, it is important to keep in mind that the greatest changes have occurred in how they work together. Williams & Bizup, 11th ed, p. 133

Men and women have changed their relationships most in how they work together. Williams & Bizup, 11th ed, p. 134

Metadiscourse

The five-paragraph essay seems to encourage this: 2/5 of the paragraphs are (possibly useless) metadiscourse.

Think back to your assignment 1. Was your introduction necessary for the audience, or was it just metadiscourse containing no useful information?

You should introduce the writing, but it should frame the relevant concerns.

Metadiscourse

Example start of memo to the PMs/founders:

The company must consider many factors concerning development of web-based products. Managers will be most concerned with overall cost of ownership, that is what I will address here. nobody: fake example

The switch from gaming to web-based products means we need something to help make the process easier. Using an HTML templating system will help make our projects look more uniform and consistent. anonymous student

Hedges & Intensifiers

Not the thing with trees.

Those words that modify your level of certainty:

The result will usually be a complete solution.

The result will obviously be a complete solution.

Hedges & Intensifiers

Too many hedges make your writing sound weak.

Quicksort is generally the fastest sorting algorithm, however merge sort may be better in some cases.

Is there really a point being made there?

Hedges & Intensifiers

Sometimes you have to actually say something.

/u/Billith

Sometimes you have to actually say something. /u/Billith

Hedges & Intensifiers

If you're stating an opinion (and that's clear from the context), then you don't have to say so.

In my opinion, scrum is the best development methodology.

Scrum is the best development methodology.

For our company, scrum is the best development methodology.

Hedges & Intensifiers

It's easy to fall into the too-many-hedges trap where statements aren't universal.

Nodes in a binary tree generally have a parent, and up to two children.

(e.g. root has no parent; leaves have no children)

Hedges & Intensifiers

Suggestion: actually say what you mean if it's short and/or relevant.

Except for the root, all nodes in a binary tree have a parent. Nodes have up to two children. In a full binary tree, all nodes have either two or zero children.

Quicksort is the fastest sorting algorithm, except when ??? where merge sort is fastest.

Hedges & Intensifiers

I find it hard to leave out the hedge if stating a not-​mathematically-​certain fact.

Canada is generally regarded as a great place to live.

This feels incomplete to the technical writer in me:

Canada is a great place to live.

Let the context and audience determine if it's necessary.

Hedges & Intensifiers

Intensifiers have their place, but lose effectiveness if used too much.

Mustache is a very good choice for our templating system, will indeed make our developers much more efficient, and of course be easy to install and configure.

Mustache is a very good choice for our templating system, will make our developers more efficient, and be easy to install and configure.

Hedges & Intensifiers

Don't under-state your case with hedges. Don't over-state with intensifiers.

Terseness

W&B rewrite this quote from Elements of Style: [205 words]

Revising is part of writing. Few writers are so expert that they can produce what they are after on the first try. Quite often you will discover, on examining the completed work, that there are serious flaws in the arrangement of the material, calling for transpositions. When this is the case, a word processor can save you time and labor as you rearrange the manuscript. You can select material on your screen and move it to a more appropriate spot, or, if you cannot find the right spot, you can move the material to the end of the manuscript until you decide whether to delete it. Some writers find that working with a printed copy of the manuscript helps them to visualize the process of change; others prefer to revise entirely on screen. Above all, do not be afraid to experiment with what you have written. Save both the original and the revised versions; you can always use the computer to restore the manuscript to its original condition, should that course seem best. Remember, it is no sign of weakness or defeat that your manuscript ends up in need of major surgery. This is a common occurrence in all writing, and among the best writers. Strunk & White, Elements of Style

Terseness

… to 99 words, then to this: [51 words]

Most writers revise because few write a perfect first draft. If you work on a computer, you can rearrange the parts by moving them around. If you save the original, you can always go back to it. Even great writers revise, so if you manuscript needs surgery, it signals no weakness. Williams & Bizup, 11th ed, p. 140

They claim to have bleached out its garrulous charm.

Terseness

I much prefer the rewritten garrulous-less version. This may be an “academic writing” vs “technical writing” distinction.

Everything should be made as simple as possible, but not simpler. maybe Einstein

We are allowed to disagree on as simple as possible.

Summary

All of these points follow the same theme: don't write crap that doesn't need to be there. Do write the crap that does need to be there.

Just like code.