writing.md (1818B)
1 I worry a lot about how efficient my writing is. I want to keep it as 2 straightforward (maximizing signal-to-noise ratio) and accurate 3 (citing sources and assumptions) as I can. 4 5 Since I keep catching myself making the same mistakes, and I do not 6 have automated tools to warn me about them yet, I figured I should 7 write down all the things I want to watch out for. 8 9 # Decruftification 10 11 ## Sentences 12 13 - Watch out for verbs which hide the action (e.g. try, allow). 14 - Use simpler words as long as they are not more vague. 15 16 ## Mails 17 18 - Pick your battles: people only have time for so many subjects. 19 Focus on symptomatic relief; hint at systemic problems but wait 20 until prompted before ranting. 21 - Tricks to make mails more digestible: 22 - condense the point(s) into a tl;dr; 23 - move details (investigation, alternatives, rationale) into 24 footnotes or attachments; 25 - spin new threads. 26 27 # Logic 28 29 When expressing causation, check that all causes have been explicitly 30 stated. Be wary of assumptions^[I felt like adding "protect yourself 31 against misquotations", but those will probably happen anyway]. 32 33 Conversely, if C can be deduced from A alone, consider rewriting 34 "since A and B, C" into "since A, C". Unnecessary Bs can be 35 detrimental to the discussion and make it to go off-topic; beware: 36 37 - humorous overstatements that might be taken seriously; 38 - subconscious attempts at shoehorning a point that feels essential 39 but is not actually relevant. 40 41 # Resources 42 43 - [IEEE's "Write Clearly and Concisely"](http://sites.ieee.org/pcs/communication-resources-for-engineers/style/write-clearly-and-concisely/) 44 - [Gitlab's Technical Writing Handbook](https://about.gitlab.com/handbook/product/technical-writing/) 45 - [Lessons from my PhD — Austin Z. Henley](https://austinhenley.com/blog/lessonsfrommyphd.html)