Saturday, January 15, 2011

Writing tip: Concise language

You are "paying" for each word, and if your idea is too expensive to communicate, it will never be heard - let alone implemented. Therefore it's imperative that developers have good writing skills if they want to become influential. One metric of good writing is that it is concise. Here is a brainstorm of tips.

Tip: Remove un-needed words and phrases

If the word adds zero value, then remove it.
//Remove "Anything about"
Anything about schemas will drive architecture.
Schema will drive architecture.

//Remove phrase "my approach"
I’ll need to confirm my approach with Bob
I’ll need to confirm with Bob

//Restructure sentence to remove the word "it"
It takes effort to ask for something.
Asking for something takes effort.
Tip: The word is implied, so you don't need it.
//Implied that you're concerned, which is why you're talking about it
My concern is that X is bad.
X is bad

//The word "something" is implied
If there’s something more to it.
If there's more to it.

//The word "about" is implied by estimate, and the number being rounded
We estimate the list to have about 10,000 rows.
We estimate the list to have 10,000 rows.

//The phrase "Ed mentioned" implies "Discussing with Ed"
Discussing with Ed yesterday, he mentioned that...
Ed mentioned yesterday that...
Tip: remove duplicate words

Sometimes people use duplicate words. Maybe because (1) they think it drives the point home, (2)
they feel like it has to be long (schools trained them to write "at least 500 words"), (3) they
can't think of a single word to describe both sub-words.
//Just pick one - either "harsh" or "ruthless"
The production environment is harsh and ruthless
The production environment is ruthless
Tip: Replace a phase with a single word
Sometimes a big phrase can be replaced with a single word because that single word is the definition of the big phrase.
//Replace the entire phrase with one word that means the same thing
The application must be able to handle an increasing amount of demand.
The application  must be scalable.
Tip: Condense two sentences into one
//Remove a descriptive sentence by applying it to the noun directly.
I'd like to set up a call. An hour should be enough time.
I'd like to set up a one-hour call.
Tip: Avoid un-needed commas
If you have a bunch of small phrases joined by multiple commas, consider restructuring it into a single sentence. Even if it doesn't make it more concise, it will probably make it easier to read.
//Remove comma
and for each line, trims it.
and trims each line.
//Merge two short sentences into 1:
We are creating a custom list. It will have 1000 rows.
We are creating a custom list containing 1000 rows.
 
//Restructure sentence
Yesterday, Ed mentioned that...
Ed mentioned yesterday that...
 
//Restructure sentence
If you approve of this design, please let me know.
Please let me know if you approve of this design.

No comments:

Post a Comment