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