Lessons learned from On Writing Well

 by Robin Wieruch
 - Edit this Post

As a software engineer you will come to a point where writing matters. Perhaps you want to leave your fellow developers a note, you have to write an e-mail to a customer or you have to sum up the recent meeting notes. In my case, it went even further because I have my own website where I write about software development and . It was about time for me to dive into the topic of writing.

The article is a summary of my lessons learned from On Writing Well by William Zinsser. I am no expert in this field, even less as a non native speaker, but by providing a summary I hope to help other developers to improve their writing skills. Apart from that it helps me to memorize my lessons learned.

I am eager to improve my language and writing skills. On Writing Well had topics which are easier applicable than other topics for non native speakers. For instance, it is easier to leave out all the clutter and keep the sentences and words simple. As a non native speaker you are less intended to write in complex sentences with difficult words. However On Writing Well had topics that were more difficult to apply. The english language has a rich set of words and synonyms that are not always known for non native speakers. Especially this fact makes it hard for non native speaker to fine tune their writing in its meaning. But let's dive into my lessons learned.

How to learn?

Repetition is the key for learning. You have to repeat. It applies for every subject you want to learn. You have to repeat and do it over and over again. "You learn to write by writing" says William Zinsser. When you produce a certain amount of words on a regular basis, you will improve eventually. But in order to learn writing well, you cannot solely use your first draft of writing. You have to refine your writing and rewrite it a dozen times. "The essence of writing is rewriting".

How to write?

Imagine you start to write about a topic. Start to think small. "Decide on the corner of the subject you want to bite off. Cover that corner well, be satisfied by that and stop." Make it a complete experience for your reader. Don't nibble on another corner of the subject and leave the reader with an incomplete reading experience.

When you write, "go with your interest". Only then the reader can get your enthusiasm and will enjoy it. Make it personal, simple and clear. However, challenge your readers, don't be too predictable when you write and let your readers think for themselves.

A Transaction

Always remember that writing and reading is a transaction between two people - an author and a reader. The topic is not the only thing that drives a reader, it is the human being behind that topic. It is the author who shows enthusiasm in his or her subject. Make the written word your own - make it personal - only then the reader will go with you.

Make it simple

Don't use difficult words to sound important. Only use them when they have purpose. Otherwise take words that are as simple as possible to make your writing as clear as possible. Use short words over long words. Same rules apply for sentences. Keep them short. Use punctuation properly to make sentences simple and cut a long sentence in two short sentences. "The short sentence predominates". Cut every word that doesn't have a purpose in the sentences. Cut every adverb whose meaning is already in the verb. You have to "strip every sentence to its cleanest components" says William Zinsser.

Make it clear

Build up your sentences in a logical order. Think in building blocks, like in a project, where each block follows another building block. Don't write by accident. Every clear sentence has been rewritten a few times until it transported the clearest meaning. You have to avoid leaving your readers in confusion. Otherwise they have to re-read the last paragraph and will eventually leave you for an author who transports the message in a simpler way.

How to remove the clutter?

How to remove all the clutter regarding the last two lessons learned? Clutter is the "disease of writing". It is unnecessary words that don't add meaning but complex sentence constructions. It is meaningless slang and duplicated sentences that convey the same meaning. You have to remove everything without purpose. Be grateful for everything you can throw away.

Especially as a technical writer avoid the growing arsenal of jargon in your field of expertise. Try to transport the meaning of your written word so that everyone can understand it. Imagine an audience of one and the one person is your spouse. Don't let your reader translate each sentence, write as simple as possible.

The quickest fix according to William Zinsser is to strike things. Ask yourself if you need the paragraph, sentence or adverb. Then keep it or strike it.

Make it Personal

Once you removed the clutter and made your text simple and clear, there might be no personal style left. But there is always a human being behind the text. Be yourself, be warm and be natural. If you can, write in the first person. Use I, me, we and us. Avoid to use one, because the reader wants to experience the transaction between a reader and writer. He or she wants to know you. Stand out as a real human. Never lack the human ingredient.

If you can't write in the first person, at least think as if you would write from your point of view. You can write your first draft in the first person. Afterwards you cut out all the I and me. Still it will keep your implicit personal style.

Believe in your opinion. Sell yourself. When your subject is your expertise, the subject will sell itself. Avoid timidities (quite, a bit, ...) in your writing. Mean it, be confident with it or strike it. Be bold.

Believe in your identity and keep your integrity. Don't fool your readers.

Know your Language (I)

The english language is rich of words. Find your personal words you want to use in your writing. Be certain about the words you use. Keep a dictionary to find their historical roots, meaning and synonyms. Use words with care and originality. Read books from people from whom you enjoy the writing. Have them as your role models.

The spoken word is looser than the written word. You should use common words over slang. Make clear what you mean. Don't "request someones input." Instead "request someones thoughts on your idea".

Unity

Stick to one set of variables. William Zinsser calls it the unity. Stick to one style and tone. Stick to one perspective. Do you write in the first or third person? Use a consistent tense. Don't switch from past tense to present tense and back again. Write formal or casual. Believe in your mood.

Don't change the set of variables in between of your writing. "If you do, the writing will control you and not the other way around". When you change variables, adjust the writing from before. However, don't overplan. You should experiment where your writing guides you. If it feels right, stick to it and adjust the variables from before. But in the end have one unity of variables.

The Lead

The most important sentence is your first sentence. The second most important sentence is the second sentence. Each sentence builds up on the other. Imagine it as an upside down pyramid whereas each sentence broadens the pyramid. The pyramid gives room for more detail. It gives room for the complexity of your topic.

Make sure that your readers know early what's in for them. State your motivation behind the article and why your reader should read it. To make it more compelling make it narrative and tell a story.

The End

The last paragraph of your writing should be short. Only take a few sentences to wrap it up. "Look for the nearest exit" says William Zinsser. You made your points and have to stop when all facts are presented. Optionally you can come back to an open question from your lead and answer it. It closes the cycle in your article or book.

Do your Research

In your research always collect more material than you will use. Research your material everywhere and don't use the obvious resources. Take interviews, articles and real world experiences into account. At some point stop to gather material. Make a clear cut and start writing.

Know your Language (II)

  • Verbs - Use strong and precise active verbs over weak passive verbs. Your verbs are the most important elements in your sentence. "They push the sentence forward and give it momentum" says William Zinsser.

  • Nouns - After verbs, plain nouns come as strong elements in your writing.

  • Adverbs and Adjectives - Avoid to use adverbs and adjectives. They weaken your verbs. Take them only when they do work for you that needs to be done. Don't write about "the green grass". Write about "grass" except it has another color than green.

  • Punctuations - Avoid exclamation points except you want to achieve a certain effect. Most of the time that effect should be achieved by your writing alone. Avoid semicolons except you want the reader to make a pause.

  • Dashes - Use dashes for two use cases: Use one dash to jusitfy the main sentence. Use two dashes in between of a sentence to add an enhancing detail.

"The tools of grammar haven't survived for so many centuries by chance; they are props the reader need and subconsciously want" - William Zinsser

  • Use that over which whenever you can.

  • Nounism is a sequence of nouns. It adds complexity. Avoid nounism where one noun or verb can describe it.

  • Keep your credibility, don't sell something as true that actually isn't.

Use Mood Changers

Mood changers are words like but, yet, however, nevertheless and still. Add them at the beginning of your sentence. As early as possible make your reader clear that something has changed. If you use too often but, you can substitute it with however. Use mood changers like meanwhile and today to make your reader aware of the time.

Make it visual

In order to keep your writing visual you have to keep your paragraphs short. Reading is visual. A reader will scan your writing and a reader will have it easier to follow you in short paragraphs. Make your writing look inviting.

Make it sound

Always listen to what you write. You can choose your words based on their sound. William Zinsser compared the words serene and tranquil whereas the one is soft and the other one is irregular because of its unusual characters. Depending on your context choose one of them.

Use the same voice in each of your writings. It comes back to the term unity. Don't adjust your voice to fit the subject. Find your simple voice and make the writing effortless for your reader. Don't add clutter like slang and nounism to the path of reading.

Rewrite Often

"Writing is an evolving process, not a finished product." Enjoy the tidying process. Strike things to make your writing simple and clear. Make it effortless for your reader. "The effortless style is achieved by strenuous effort and constant refining." Push your personality into your writing with each rewrite.


The last paragraph form the last chapter, "Write as Well as You Can", is still stuck in my head. It doesn't necessarily apply only to writing, but to all our doings:

A reporter once asked him [a baseball player] how he managed to play so well so consistently, and he said "I always thought that there was at least one person in the stands who had never seen me play, and I didn't want to let him down."

I can recommend to read the book On Writing Well by William Zinsser. It taught me a lot. But these are only my lessons learned. Maybe you can distill other learnings when you read it.

Keep reading about 

React Function Components -- also known as React Functional Components -- are the status quo of writing modern React applications. In the past, there have been various React Component Types , but…

Writing tests is an essential part of software development to ensure a robust application. Tests enable us to automatically verify that our application is working on a certain level. The certain level…

The Road to React

Learn React by building real world applications. No setup configuration. No tooling. Plain React in 200+ pages of learning material. Learn React like 50.000+ readers.

Get it on Amazon.