#breakdown
Explain things directly Don't add fluff words that aren't necessary (easy, simple, just, etc) Don't say it's easy, show them it's easy You can do this by explaining things in a clear manner, properly showing tradeoffs, etc. You effectively leave them thinking that your idea is an idea that makes sense.
Use plain language Keep it simple Makes your text more relatable and concise Don't convince someone with language, be persuasive through structure/framing.
Organise content with lists, tables, and headlines Makes your text easier to parse
Get a peer review Extra eyes helps avoid mistakes
Get to the point quickly, that's what people care about
Write to someone who has no idea what you do. People may not have context, but they should still be able to understand what you're trying to convey
Fewer commas. More periods.
Don't use adverbs, replace the adverb + verb with a better verb instead.
Look out for sentences starting with ‘There is’ or ‘There are’ as you can often rewrite them for more clarity. ‘There are no studies that have examined this effect’ can be rewritten as ‘No studies have examined this effect’.
Recast ‘of the’ constructions as possessive Overuse of ‘of the’ in a sentence can result in sluggish writing, which can interrupt the flow. This can simply be fixed by recasting as possessive. ‘We sought the perspectives of the students’ can be recast as ‘We sought students’ perspectives’.
Avoid overuse of ‘that’ in a sentence I’ve found in some scholarly writing, authors often overuse the word ‘that’, which can make a sentence seem long-winded and unwieldy. They can often be removed with no other changes.
Writing is critical ar larger organisations because messages reach a bigger audience. For engineers, writing is a mean to reach, converse with, and influence engineers and teams outside their immediate peer group.
Re-read your writing by putting yourself in the recipient's shoes. This helps nail the tone, contents, context, etc.
Be concise. Shorter sentences, less distracting elements, etc. The longer the writing, the more tiring it is for readers. https://hemingwayapp.com/
A picture is worth a thousand words. This also applies to technical writing.
Value the reader's time more than your own. This saves time overall too [[20211203043016-writing-saves-time]]
Ask for feedback before publishing your writing. Another pair of eyes always helps. When facilitating feedback, ask people directed questions.
Try to avoid using 'this' or 'us', when you can be more explicit. Same with 'they' or 'it'
For clear writing, answer these questions
What Am I Really Trying To Say
Why Should People Care
What Is The Most Important Point
What Is The Easiest Way To Understand The Most Important Point
How Do I Want The Reader To Feel
What Should The Reader Do Next
https://twitter.com/shreyas/status/1285460711808700418
The realization that you don’t have the complete message in your head, will often only become apparent while writing. This surfaces as inability to find a good punch-line or to express yourself clearly. In fact, writing is a great test to see if you have a good understanding of a topic, and have a firm grasp on the vocabulary of the domain. Writing is generally a great way to learn, but one has to realize that you are doing it.
Andrew note: anecdotally I find my spike documents to suffer from this. Might be a good idea to keep the learning part of the spike separate from the end artifact.
Writing requires intense focus over long periods of time. Ideally you want to get into a flow state where you are zoned in and working on the text for hours on-end.
Prepare for a writing task, like you would for a hike. You are in for a grind. Find a comfortable space to sit. Grab a beverage/snack of your preference. Most importantly make sure that you are rested and able to focus. Don’t start a writing task when you are already tired. There is no way you will get anything useful written.
Also, avoid distractions as much as you can.
Just like programming, writing requires a lot of context that you hold in your short term memory. You need to recall a lot of details about the topic you are writing about, as well as your punch-line and the current state of the document. All this state takes time to load into memory, and is easily lost by distractions or context switching.
If you have loaded a lot of useful context in your brain at any given point in time, use this context to do something useful with it. Try to milk that moment, and make space when you realize you are in a position to write effectively on your topic.
This is by far the most common and damaging mistake I see people make. They start with writing at the beginning of the narrative:
“Once upon a time, in a galaxy far, far away …”
Do you really think that those were the first words that George Lucas brought to paper, when writing the original Star Wars trilogy?
For documents that are more than a page long you must take a top-down approach and start with an outline. An outline is a list of sections together with rough notes, often in the form of bullet points. For this document the first outline looked something like this:
When building a house, you finish the brick-work before applying the paint. When writing, you want to arrive at a good story-line for you document, before you start fleshing out and polishing the text. A outline should be the first milestone for any larger document you are writing. The outline, should convey the main message and provide a clear “red thread” that guides your reader through your argument.
When working for a consulting firm, I saw my senior colleagues spending a lot of time polishing and iterating the structure of their slide decks before working on the details. They would print the deck on paper, pin the slides to a wall, and keep re-arranging them until they were happy with the story-line. The slides would remain on the wall and subject to re-arrangement until the deck was finalized.
Fixing the story-line of a document becomes MUCH more expensive once you have already fleshed out the paragraphs. In some cases, the best thing you can do is to stash away the whole content and go back to an outline before building the document up again.
https://www.heinrichhartmann.com/posts/writing/