Technical writing tips
- Reduce cognitive load for the reader:
- Unsurprisingly, people struggle to absorb new material when their working memory is already overloaded.[1] And fluid IQ declines with age and that's why a very basic writing style is often better at least for technical writing. Older people are also often busier and more important, so if you want your writing to be read by older people you should reduce the cognitive load for the reader.
- Sentences: Shorten long sentences to ~20 words to increase readability[2]- err on the side of breaking them up; use fewer clauses; no redundancy; unnecessary adjectives; reduce need to recall references to other parts of the sentence (e.g. constructions like 'the former and the latter'). Reduce abbreviations. etc. Unnecessarily taxes working memory
- You can start a sentence with 'And:'
- You can also ctrl+f for 'which'- start a new sentence and replace this with 'this'
- Find and Replace 'That': A common rule of thumb is that in many sentences, everything before the word 'that' can be deleted (e.g., 'It is usually the case that...'-> 'Usually...').
- Good video on editing
- Limit paragraphs to 500-characters (in Google docs count them with Cmd+Shift+C).
- Titles should also be short[3]
- Sentences are easier to understand when larger phrases are placed later.[4]
- Put adjectives close to nouns.[5]
- Cut the 5 dollar words: Forcing yourself to use a limited vocabulary (like the 1,000 most common words, as in Thing Explainer, or Dr. Seuss's 236 words) can reveal new insights and force you to simplify complex ideas. The word frequency effect shows that recognition times are faster for words seen more frequently than for words seen less frequently.
- Use German words:
- 'Every word has a unique weight, determined as much by connotation as denotation. A 'lie' is weightier than a 'prevarication'; a 'blue' sky is homelier than an 'azure' one. As these examples suggest, the weight of a word often has to do with its etymology, especially in English, with its double heritage of Latinate and Germanic words
- In England after the Norman Conquest, the wealthy and powerful spoke French while the commoners spoke Anglo-Saxon, and these associations continue to shape the language a thousand years later. polysyllabic words derived from Greek and Latin—'mystic,' 'cosmetic,' 'inferior'—reinforce the sense that we are in a sophisticated milieu. By contrast, use of words with Anglo-Saxon roots sound simple and primal—'mould,' 'big-boned,' 'hardy.' '
- 'Brevity is selection, not compression'. Cut whenever a paragraph doesn't advance the central point of your essay. If you can't let go and 'kill your darlings', move your darlings to footnotes or the appendix
- Hunt for Un-defined 'The's': As a philosophical heuristic, Ctrl+F for the word 'the' and ask yourself if the noun it's pointing to is clearly defined and understood.
- Don't Repeat Misconceptions: When refuting a point, don't say 'X isn't true.' This reinforces X. Instead, just state the positive case: 'Here's why Y is important.'
- Use 'Top-Down' Paragraphs: Structure your paragraphs with the 'top-down approach.' State the main idea, claim, or theme prominently in the very first sentence. This is easiest for readers to skim and comprehend.
- Style:
- Use E-prime: Reduce forms of the verb 'to be', you can ctrl+f (are, am, is, was, were, be, been, being and contractions), which will force you to make your writing more forceful.
- Leverage the human visual system to improve understanding. Fluid mechanics make for great metaphors. In contrast to animal metaphors, water metaphors are more about describing mechanical causal models. In general, use metaphors that relate to fundamental human experiences that aren't culturally specific (e.g. bottlenecks, pain points and choke points). When writing, think about the physical metaphor going on in your mind. Bostrom does that a lot- for instance:
- 'For a visual analogy, picture a box with large but finite volume, representing the space of basic capabilities that could be obtained through some possible technology. Imagine sand being poured into this box, representing research effort. The way in which you pour the sand will determine the places and speed at which piles build up in the box. Yet if you keep pouring, eventually the whole space gets filled.'
- 'These circumstances of birth of a new technology, which shape its impact, can be affected by turning funding spigots on or off (and by wielding other policy instruments). These reflections suggest a principle that would have us attend to the relative speed with which different technologies are developed'
- Those who seek the advancement of human knowledge should focus more on these kinds of indirect contribution. A 'superficial' contribution that facilitates work across a wide range of domains can be worth much more than a relatively 'profound' contribution limited to one narrow field, just as a lake can contain a lot more water than a well, even if the well is deeper.
- Bostrom also uses bullet points, so you can do that too
- Philosophy
- Better Wrong Than Vague: Using logical operators can sometimes be useful for that. Only if you do that will your writing be strong and easily falsifiable.
- Use 'Bayesian' Words: Start sentences with words that signal a shift in your own understanding or surprise, such as 'Surprisingly,' 'Unexpectedly,' or 'Tellingly.' This frames your points as updates to a model.
- Test Arguments with Extreme Cases: A practical philosophical heuristic. When you make a claim, ask yourself, 'Does this argument hold for the most extreme, borderline cases?'
- Use the Mumford methods
- Research:
- Don't roll your own: Probably someone has already written about your topic. Use 'Forward Search'. Instead of only looking at what a paper cited (backward search), use the 'Cited by' button on Google Scholar to find all the newer papers that are built on it. This gets you to the frontier of knowledge.
- Use more inference: 'It is not that I'm so smart. But I stay with the questions much longer.'
- Editing:
- Create an Audio-Editing Workflow: Publish your doc to the web, add that private URL to an app like Pocket or Elevenreader, and listen to the text-to-speech version of your article while on a walk.
- Print + Pen Workflow: Print doc → read with pen → mark up → implement edits. Helps you not get distracted by your computer.
- Guard Your Morning Attention:
- Wake up and start researching and writing. Do not check anything. It clogs your working memory for the day. Also see What Is The Morning Writing Effect?
Paul Graham:
As for how to write well, here's the short version: Write a bad version 1 as fast as you can; rewrite it over and over; cut out everything unnecessary; write in a conversational tone; develop a nose for bad writing, so you can see and fix it in yours; imitate writers you like; if you can't get started, tell someone what you plan to write about, then write down what you said; expect 80% of the ideas in an essay to happen after you start writing it, and 50% of those you start with to be wrong; be confident enough to cut; have friends you trust read your stuff and tell you which bits are confusing or drag; don't (always) make detailed outlines; mull ideas over for a few days before writing; carry a small notebook or scrap paper with you; start writing when you think of the first sentence; if a deadline forces you to start before that, just say the most important sentence first; write about stuff you like; don't try to sound impressive; don't hesitate to change the topic on the fly; use footnotes to contain digressions; use anaphora to knit sentences together; read your essays out loud to see (a) where you stumble over awkward phrases and (b) which bits are boring (the paragraphs you dread reading); try to tell the reader something new and useful; work in fairly big quanta of time; when you restart, begin by rereading what you have so far; when you finish, leave yourself something easy to start with; accumulate notes for topics you plan to cover at the bottom of the file; don't feel obliged to cover any of them; write for a reader who won't read the essay as carefully as you do, just as pop songs are designed to sound ok on crappy car radios; if you say anything mistaken, fix it immediately; ask friends which sentence you'll regret most; go back and tone down harsh remarks; publish stuff online, because an audience makes you write more, and thus generate more ideas; print out drafts instead of just looking at them on the screen; use simple, germanic words; learn to distinguish surprises from digressions; learn to recognize the approach of an ending, and when one appears, grab it.