Thoughts on Writing
What is it your reader needs to do, feel, think, decide, or understand? Help your reader to achieve that as quickly as possible, and never exceed 10 seconds to get your main point across.
Readers have a limited amount of patience and a finite attention span. Do not make your readers wade through multiple semi-related points and/or a selection of your incoherent thoughts before you get to the point.
Plan for five versions
Write the way you code.
- The first version is for you. It is awful and that is OK. No one else is going to read it: it is the equivalent of a hacky script that gets the job more or less done but requires extensive refactoring.
- The second version is to re-organize:
- Move paragraphs around (organize code into objects, files, etc.)
- Add supporting documents and links (rely on libraries and common tools)
- Add sections and captions (add comments and structure)
- Add images (in-code diagrams or API documentation)
- Check the main argument (unit tests)
- The third version is to trim the fat and rephrase for clarity (inconsistent naming, duplication of code, proper linting and in-house styling, …)
- The fourth version is open for limited feedback (pull/merge request)
- The fifth version is for wider readership (commit to main/master)
Why treat text with less care than code? The answer is obvious: it takes a lot of time to do it properly. Then again, your readers will thank you and so will you. When you have to re-read your own document after a few months, you will still understand the main points, because you have made them clear and easy to grasp.
BLUF
You are (probably) not a Hollywood writer who needs to have a great season ending to make people want to read on. Let them know why they ought to start or continue reading. In military parlance, that is known as BLUF: Bottom Line Up Front. It means you ‘lead with the need’ if you can stomach business-speak.
Some people take this rule to the extreme and force the first sentence of every paragraph to be the main point of that paragraph. I do not personally follow that rule, but it may help in structuring your thinking, so use it if (and only if) it helps.
Clarity starts with you
If thoughts are not clear in your own mind, you cannot expect that whatever text you produce is going to be crystal clear to your readers. In fact, the clarity you have is at best the clarity your readers will have. In that sense, clarity begins and ends with the author.
How can you be clearer? A simple trick is to sleep on it. Often a fresh pair of eyes read a text differently than two eyes that have seen the same text for a whole day. But make sure you read it, not skim it. Just pretend you did not write the document and you are reviewing your own work as an outsider. You want to critically examine your ideas, not just check that the formatting is consistent.
Write for the reader
Read the text from your reader’s unique perspective. Look at jargon and abbreviations and ask yourself if the audience is familiar with the terms? Are the style and language appropriate?
Connect on an emotional level if possible. People will forget numbers, people will forget funny jokes (or attempts at making jokes), but they won’t forget how they felt when you made your point: bored, engaged, scared, confused, excited, sad, angry, happy, and so on. This is sometimes referred to as ‘storytelling’ and it is just a trick to make your writing worth remembering.
Add levity
If you are strictly formulaic for 20 frickin’ pages, people are going to fall asleep. If on the other hand, every other paragraph is a joke, people won’t take you seriously. Likewise, if you can make Samuel L. Jackson blush, you are probably overdoing the profanities a little bit.
Format properly
While many pros proclaim that a good text does not have to be formatted and made to look great, they are liars. When people claim they do not have the time for frivolous matters such as formatting or typesetting, they are merely making it clear that your time does not matter to them. In that case, why bother reading? Being easy on the eye matters when you have to trawl through pages and pages of text.
Don’t get attached
Sometimes you have crafted a beautiful sentence with a double entendre that you know people are going to appreciate, or you added a quirky reference to a movie only three people have seen but you really want to include it. Then you start editing and notice it ruins the flow. You try to crowbar that sentence into the paragraph and write supporting text to introduce it, and, and, and, …
Kill it! It is essential if you want to write concisely. If you are really that proud of your creation, copy-paste it into your diary. That way, you keep it around, but you do not bother others with it.
Use images wisely
A picture may be worth a thousand words, but some people write those thousand words, because creating a picture that explains something clearly also requires a lot of work. People underestimate the effort it takes to make a picture say something. Do not make that mistake. Learning to edit down to the essence requires practice. And a few iterations.
Don’t expect people to read everything
Even at the best of times, people can only retain 5–7 pieces of information in their short-term memory. If you have a crucial point to make, make it a few times in different guises. Tell a memorable story that highlights it, show a chart that makes it clear, do whatever it takes to make that point, but do not water it down with lots of other semi-important points you want to make too.
If there is one thing people should take away from your document or presentation, make that absolutely clear. The rest is just there to make that point clearer. If it does not, drop it.
Afterword
Who made me the king of writing? Nobody. These are just some rules I (mostly) live by.