Also: this book is great: https://www.amazon.com/Style-Clarity-Chicago-Writing-Publish...
https://www.amazon.com/Style-Clarity-Chicago-Writing-Publish...
He says that to achieve clarity, imagine the subject of each sentence as the character of a scene, and the verb as its action. Make sure you hit both character and action within the first 6-10 words of your sentence.
Begin each sentence with information that the reader is familiar with, and end it with the new information you want to introduce.
That will get you a long way toward creating understanding (and feeling) in the reader.
https://www.amazon.com/Style-Clarity-Chicago-Writing-Publish...
The chapters from 1 through Cohesion II are better at teaching clarity of thought in writing than any I've read anywhere. Most books focus on grammar and style and ignore the good stuff in between.
For those who like Williams, he also wrote books on how to build arguments and conduct research!
-----
For learning to edit a piece of writing you've already written, I recommend this book: https://www.amazon.co.uk/Style-Clarity-Chicago-Writing-Publi... It is full of advice more actionable than Strunk and White.
-----
For learning how to write a first draft without wanting to dig your nails into your arms or more drastic forms of self-harm, I recommend:
1) "Start with Why" -- Start each draft by writing your goal and then writing the "signs of success" which you can use to recognize making progress.
I find a particularly motivating form of "why" is a description of a problem someone finds themselves in which they want advice about. Reddit is a good source of these if you want inspiration, but you might be better off giving advice to your future self.
2) Take inspiration from automated testing -- If you are anxious about some section being [maliciously] misinterpreted, write down that anxiety with a pointer to the section and a promise to yourself to have a trusted friend read it.
3) Question-Driven-Drafting -- Start with a question. Write the first flawed answer that comes to mind. Write the first question or objection that comes to mind from that answer. Write the first response that comes to mind from that etc... Don't delete.
4) Alternate focusing with exploring -- Set a pomodoro timer. Use my method from #3 or another to produce a bunch of text. When it goes off, congratulate yourself and meditate for 2 minutes. Then set another pomodoro timer and start to turn your ideas into a structured outline: Try to extract the one-sentence key point from the text you just wrote. Then try to build a pyramid-shaped hierarchy under it with the names of the supporting points. When this pomodoro ends, meditate again and start another rambling pomodoro based on the most interesting point.
5) Be willing to "overthink things" -- When you have a question, be willing to actually trust yourself that the question is worth answering. If someone else thinks the answer is obvious, just move on to ask someone else. If someone screams at you that your question is excuse-making, bullshit, or procrastinating, just move on from them. You no longer have parents nor teachers to endure and can write from your own desire to understand the world and communicate ideas. The confusion you notice in yourself is worthy not of ridicule but of sympathetic curiosity.
6) Go for a walk -- Its just a generally good idea.
7) Dictate into otter.ai -- It is as good a use for your time while walking as any. The resulting text will be heavy with misspellings, but you'll be able to edit it and it will restore your sense of confidence in your ability to generate ideas.
8) Work with a writing coach or therapist if you can find a good one. They might be expensive, but they're less expensive than getting fired because you handed in a blank performance self-evaluation.
I certainly didn't learn how to write clearly at University and I had to write loads of reports and essays for 5 years.
I actually owe a great debt of gratitude to my first job out of University where I worked as an analyst for a finance and economics consultancy. The CEO was fanatical about making everything Plain English writing style. It was a trial by fire.
Anyway, my advice is to go on a Plain English writing course. The course instructors usually critique your writing and offer helpful insights on how to improve. If that's not possible, go through the guides on the Plain English website (http://www.plainenglish.co.uk/free-guides.html). I also highly recommend applying the writing principals in Style: Toward Clarity and Grace (http://www.amazon.co.uk/Style-Clarity-Chicago-Writing-Publis...). This book is worth its weight in gold.
And "Style: Towards Clarity and Grace" for a more humble, direct, simple style for non-complex presentation: (Non-aff) http://www.amazon.com/Style-Clarity-Chicago-Writing-Publishi...
The patronizing part wasn't the non-programmer part and making fun of programmers. I actually loved the line about VI/Emacs. It was the overly simplified sentences. Let me dig the pdf out:
You can print things out with print and you can do math. The next step is to learn about variables. In programming a variable is nothing more than a name for something so you can use the name rather than the something as you code. Programmers use these variable names to make their code read more like English, and because programmers have a lousy ability to remember things. If they didn’t use good names for things in their software they’d get lost when they came back and tried to read their code again.
For instance in this section your actual sentences are very simple. Over and over you use these simple sentences. And you use an explicit "you". It gives the feel of a children's book (I don't know if you have kids, but if not, google for some of the books or ask a co-worker to borrow some). I think explicit "you" is fine, but the constant reassurance compounded with the sentence structure and explicit "you" feels patronizing.
Other examples:
You might not know it, but every time you put " (double-quotes) around a piece of text you’ve been making a string.
Most of these concepts will be exciting once you get them. You’ll struggle with them, like wrestling a squid, then one day snap you’ll understand it.
I know several people professionally who'd benefit from the book if you upped the "implicit respect" of the style a few notches. However, I'd be afraid to give it to a few of them out of fear of insulting them with the way some people will interpret the tone. I'm putting this out there in all earnestness.
Here are a couple books on two different styles which might be more applicable for the work. They are on actual explicit styles of writing, although the second pretends all writing should look like that.
Clear and Simple as the Truth by Thomas & Turner (Classic style).
Nonafflink: http://www.amazon.com/Clear-Simple-As-Truth-Writing/dp/06910...
Example of classic style:
When I was a boy, there was but one permanent ambition among my comrades in our village footnote [1. Hannibal, Missouri] on the west bank of the Mississippi River. That was, to be a steamboatman. We had transient ambitions of other sorts, but they were only transient. When a circus came and went, it left us all burning to become clowns; .... now and then we had a hope that if we lived and were good, God would permit us to be pirates. These ambitions faded out, each in its turn; but the ambition to be a steamboatman always remained. --Mark Twain
Style by Williams (Plain Style):
Nonafflink: http://www.amazon.com/Style-Clarity-Chicago-Writing-Publishi...
Example: After Peter the Great died, seven out of eight reigns of the Romanov line were plagued by turmoil over disputed succession to the throne. -- Williams edit to uncredited work on Russia
