.png)
10 hours ago
2
“Clear thinking becomes clear writing.” - William Zinsser.
I just finished reading the book “On Writing Well” by William Zinsser. It left a mixed impression. Some chapters were excellent, while others weren’t useful at all to me. Many dragged on too long - which felt ironic, given the author advice to keep everything simple and cut unnecessary details. But most importantly, I agree with key ideas of the book: use simple and accurate words, write concise and clear sentences and remove anything that hurts readability. It reminds me of basic principles of software engineering when we try to write code as simple as possible.
We have natural complexity of the ideas we are explaining to the readers. Some of them can be extremely hard to explain and it is impossible to reduce its natural complexity. But we control how we explain it and keep additional complexity at reasonable level. While building software we should keep short but precise variable names, small functions with clear logic which is easy to follow and solid abstractions. The author proposes similar principles during writing texts.
We should express our ideas so plainly that readers grasp them instantly without rereading. This sounds obvious, but it demands clear thinking before we start writing. We must understand what we’re writing about and have solid knowledge of the topic.
This principle applies to programming as well. Before writing production code, we must clearly understand what we want to achieve, how we’ll do it, and the scope of the project.
Keep It Simple, Stupid! We should use the simplest sentences and words that still fully express your idea. Can we delete a part of the sentence without losing anything? Then delete it.
The same applies to code. We have books written about short functions and short but meaningful variable names. We have programming languages designed with this principle first!
Clutter is all the noise in your sentences which harms clarity. So, carefully examine your sentences for:
Every word that doesn’t serve any function.
Every long word which can be safely replaced with a short one.
Every adverb that has the same meaning as the verb.
Every passive construction which leaves the reader unsure who is doing what.
…and delete them.
When code has a surplus of functions or unnecessary lines, it harms maintainability. Good engineers take pride in keeping their codebase clean - I don’t know any good software engineer who doesn’t enjoy removing unused variables, redundant functions, deprecated services, and repositories.
Rewriting is the key to good writing. Each iteration refines your text and improves clarity. No one can write sentences that are both concise and complete without rewriting them a couple of times. Writing well is hard work.
What about code? I still rewrite my code at least 1-2 times before making my PRs ready for review. I don’t believe that anyone can produce well-written code from the first attempt. Even after deploying to production, refactoring makes sense if you see how the code’s clarity. Obviously, every change leads to a risk of instability. But the risk is negligible if the service is written well using automatic tests and the team follows good deployment practices.
Unity has two aspects. First is unity of form: keep the same tone, tense, and style. Second is unity of sense. Every part of our writing should serve the same central idea.
What about software engineering? Consistency in code style and terminology is very important, and many books highlight it. Unity of sense in one module is highlighted in many principles: Single Responsibility Principle in SOLID, High Cohesion in GRASP.
A writer should use simple but not poor words. The right word is a powerful tool - we should use a dictionary to explore into nuances of meanings or find synonyms. One accurate word can replace a whole sentence. But we should avoid repeating the same words and cliches, as it kills the reader’s interest.
What about software engineering? Naming is important as well. Sometimes we have battles over naming variables in PRs! However, cliches are the best friend for any engineer, as repeating the same principles and using the same words for them reduces cognitive complexity for experienced engineers.
While reading this book, I realised that writing a good article follows similar principles as writing a good piece of software. The main difference is in the tooling — writers use English instead of Golang, C#, Java, etc.
I like this book and agree with its core principles of writing. It helped me clarify how to write good English text and gave me fresh ideas about writing. However, I found some chapters too long — Keep It Simple Short! Several chapters didn’t interest me; they covered sport writing and art criticism, which aren’t relevant to me. Relevant patterns are covered in “Writing For Developers“ so well though, I didn’t need them it in this book anyway. My verdict: this book deserves a place on a shelf if you want to write well. Or do you have better recommendation for a book about writing good English?
