A place to cache linked articles (think custom and personal wayback machine)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

index.md 18KB

2 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  1. title: Writing for Engineers
  2. url: https://www.heinrichhartmann.com/posts/writing/
  3. hash_url: 26b53a6e8889416c87357fd76cc5d951
  4. <p>Writing is key to have impact in large organizations. As a senior software
  5. engineer chances are that writing is the most important skill you have to
  6. acquire in order to increase your scope beyond the team and advance your career.</p>
  7. <p>Writing is hard. Many Software engineers struggle with writing. Personally I
  8. never had an intrinsic interest in literature, so writing did not naturally come
  9. to me either. I have spent days and weeks agonizing and procrastinating around
  10. larger writing tasks. And to this day, having pressure to produce high-quality
  11. documents on a deadline gives me nightmares.</p>
  12. <p>This article contains some learnings that have helped me (and others) to become
  13. better and more productive as a writer over the past 15 years. I am sharing them
  14. in the hope, that you find them useful. However, don’t think that I am always
  15. able to follow this advice myself 😅. I still have a lot to learn.</p>
  16. <h2 id="before-you-begin">Before you begin</h2>
  17. <h3 id="have-something-to-say">Have something to say</h3>
  18. <p>This statement seems obvious, but turns out to be a problem surprisingly often.
  19. <strong>The goal of writing is to deliver a message to an audience in an effective
  20. way.</strong> If you don’t have a good message, you will struggle to write something
  21. useful.</p>
  22. <blockquote>
  23. <p>During my time at University, I was tasked multiple times with writing long
  24. reporting documents for EU projects. This was terrible experience, because the
  25. main goal was to look good and fill pages. Generally, I had a good idea of the
  26. domain, but did not have a clear message or sufficient depth. For me, this made
  27. it incredibly hard to write anything. Thinking about this now, I think
  28. <a href="https://en.wikipedia.org/wiki/GPT-3">GPT-3</a> would be amazing at writing EU
  29. Project reports.</p>
  30. </blockquote>
  31. <blockquote>
  32. <p>One of my most successful <a href="https://www.circonus.com/2018/08/latency-slos-done-right/">blog
  33. posts</a> (that led to a
  34. <a href="https://archive.fosdem.org/2019/schedule/event/latency_slos_done_right/">series</a>
  35. <a href="https://www.usenix.org/conference/srecon19asia/presentation/schlossnagle-latency">of</a>
  36. <a href="https://www.usenix.org/conference/srecon19americas/presentation/moyer">talks</a>
  37. on the topic) was written over the course of 3 hours in a hotel room, and
  38. published the next day. It was a followup to a discussion that I had on that
  39. same day with a few Google SREs at SRECon EMEA 2018. I knew what I wanted to
  40. say. I knew who I wanted to reach. That made writing the post super easy.</p>
  41. </blockquote>
  42. <p>If you don’t have a clear message in your head, your are not ready to start
  43. writing a narrative yet. You have other things to do first: Research the topic
  44. and find your message. It’s important to realize that these are different tasks.
  45. They may involve writing in the form of note-taking or journaling, but this is
  46. not material you would directly use in the final document.</p>
  47. <h3 id="dont-confuse-writing-and-learning">Don’t confuse writing and learning</h3>
  48. <p>The realization that you don’t have the complete message in your head, will
  49. often only become apparent while writing. This surfaces as inability to find a
  50. good punch-line or to express yourself clearly. In fact, writing is a great test
  51. to see if you have a good understanding of a topic, and have a firm grasp on the
  52. vocabulary of the domain. There is a saying that:</p>
  53. <blockquote>
  54. <p>Writing is god’s way to show you how imperfect your thoughts are.</p>
  55. </blockquote>
  56. <p>And similarly:</p>
  57. <blockquote>
  58. <p>An argument is only half as good once you are uttering it.</p>
  59. </blockquote>
  60. <p>If you run into this problem, it means that you are learning things. Writing is
  61. generally a great way to learn, but one has to realize that you are doing it.
  62. Learning is a slow process and requires patience. It is not helped much by
  63. agonizing in front of a screen, trying to squeeze out another sentence. Doing
  64. more research on the topic by reading a book, blog or paper and taking notes may
  65. be a better time investment.</p>
  66. <h3 id="know-your-audience">Know your audience</h3>
  67. <p>The better you know and understand your audience the easier it will be to reach
  68. the goal of delivering a message to them. The intended audience of the text
  69. influences the terminology you can use, the context you can assume and the
  70. writing style (casual/formal).</p>
  71. <p>When writing an article, I generally <strong>visualize a concrete person as
  72. representative of the audience</strong>, that I am directing this text towards. This
  73. will usually also be the first person, that will get a draft to read. It’s
  74. generally much easier to tell a story “to someone” as opposed to talking into
  75. the void.</p>
  76. <blockquote>
  77. <p>Most of my <a href="/#math">#math</a> posts on this blog are actually lacking a good
  78. audience. They are only readable for people who are proficient in abstract
  79. mathematics, but they are only interesting for people working in software. The
  80. intersection of both groups is tiny. Hence I don’t expect a lot of resonance or
  81. impact with those. They are documenting things that I wanted to learn myself.</p>
  82. </blockquote>
  83. <h3 id="respect-your-state-of-mind">Respect your state-of-mind</h3>
  84. <p>Writing requires intense focus over long periods of time. Ideally you want to
  85. get into a flow state where you are zoned in and working on the text for hours
  86. on-end. This is by far the most efficient way to write a narrative or a
  87. blog-post – at least for me.</p>
  88. <p><strong>Prepare for a writing task, like you would for a hike. You are in for a grind.</strong>
  89. Find a comfortable space to sit. Grab a beverage/snack of your preference. Most
  90. importantly make sure that you are rested and able to focus. Don’t start a
  91. writing task when you are already tired. There is no way you will get anything
  92. useful written.</p>
  93. <p>Also, avoid distractions as much as you can. Most importantly: Mute the Chat.
  94. Block at least 3h in your calendar for a writing session. If I am writing longer
  95. documents for work, I will try to block a full afternoon. For me, the most
  96. effective writing sessions happen on weekends or vacations where I don’t have
  97. any meetings at all.</p>
  98. <h3 id="work-the-iron-while-its-hot">Work the iron while it’s hot</h3>
  99. <p>Just like programming, writing requires a lot of context that you hold in your
  100. short term memory. You need to recall a lot of details about the topic you are
  101. writing about, as well as your punch-line and the current state of the document.
  102. All this state takes time to load into memory, and is easily lost by
  103. distractions or context switching.</p>
  104. <p>If you have loaded a lot of useful context in your brain at any given point in
  105. time, use this context to do something useful with it. Try to milk that moment,
  106. and make space when you realize you are in a position to write effectively on
  107. your topic.</p>
  108. <h3 id="heat-the-iron-before-working-it">Heat the iron before working it</h3>
  109. <p>Conversely, if you don’t have the context in your brain right now, you have
  110. two options (1) don’t write or (2) start loading the context into your brain.</p>
  111. <p>Missing context is a frequent source of agony and procrastination. Don’t expect
  112. to take a TODO like “Write conference talk” from your list, and start working on
  113. it right way. You need to invest time into loading context before you have a
  114. chance to write even a single sentence.</p>
  115. <p>Good ways to load some context are:</p>
  116. <ol>
  117. <li>Go through your notes that you took about the topic.</li>
  118. <li>Discuss the topic with a coworker / random stranger / family member.</li>
  119. <li>Read some books / blogs / papers on the topic.</li>
  120. </ol>
  121. <p>Bad ways to load the context are surfing HackerNews or YouTube.</p>
  122. <h2 id="while-writing">While writing</h2>
  123. <h3 id="start-at-the-top-not-the-beginning">Start at the Top not the Beginning</h3>
  124. <p>This is by far the most common and damaging mistake I see people make. They
  125. start with writing at the beginning of the narrative:</p>
  126. <blockquote>
  127. <p>“Once upon a time, in a galaxy far, far away …”</p>
  128. </blockquote>
  129. <p>Do you really think that those were the first words that George Lucas brought
  130. to paper, when writing the original Star Wars trilogy?</p>
  131. <p>For documents that are more than a page long you must take a top-down approach
  132. and start with an <strong>outline</strong>. An outline is a list of sections together with
  133. rough notes, often in the form of bullet points. For this document the <a href="https://github.com/HeinrichHartmann/HeinrichHartmann.github.io/commit/46be4c95faeda16996baf6799eca8a551b282565">first
  134. outline</a> looked something like this:</p>
  135. <pre tabindex="0"><code># How to Write?
  136. - Audience: Senior+ SWE
  137. - Goal: Upskill and unblock writing
  138. ## Have something to say
  139. - Goal: Deliver message to audience.
  140. - Without message writing is agony: Squeezing a water from a stone.
  141. ## Know your audience
  142. ## Work the iron while it's hot
  143. - Be aware of your brain context
  144. - Start/Stay on task, if you have the right context
  145. - Load context before you start
  146. ## Separate Editing, Publishing and Writing
  147. - If you are fiddling with git/emacs before starting to write,
  148. you are doing something wrong.
  149. ...
  150. </code></pre><p>Note that, the section titles are not just generic scaffolding (e.g.
  151. “Introduction” / “Body” / “Conclusion”) but already tell the whole story.</p>
  152. <h3 id="fix-the-story-line-before-fleshing-things-out">Fix the story-line before fleshing things out</h3>
  153. <p>When building a house, you finish the brick-work before applying the paint. When
  154. writing, you want to arrive at a good story-line for you document, before you
  155. start fleshing out and polishing the text. A outline should be the
  156. first milestone for any larger document you are writing. The outline, should
  157. convey the main message and provide a clear “red thread” that guides your reader
  158. through your argument.</p>
  159. <blockquote>
  160. <p>When working for <a href="https://www.mckinsey.com/">a consulting firm</a>, I saw my
  161. senior colleagues spending a lot of time polishing and iterating the structure
  162. of their slide decks before working on the details. They would print the deck on
  163. paper, pin the slides to a wall, and keep re-arranging them until they were
  164. happy with the story-line. The slides would remain on the wall and subject to
  165. re-arrangement until the deck was finalized.</p>
  166. </blockquote>
  167. <p>Fixing the story-line of a document becomes MUCH more expensive once you have
  168. already fleshed out the paragraphs. In some cases, the best thing you can do
  169. is to stash away the whole content and go back to an outline before building
  170. the document up again.</p>
  171. <h3 id="finish-the-content-before-starting-to-polish">Finish the content before starting to polish</h3>
  172. <p>A trap I have found myself in way too many times, is to get distracted by
  173. adjacent tasks that are not needed to produce the narrative. Those tasks
  174. include:</p>
  175. <ol>
  176. <li><strong>Editing</strong>. Fixing spelling, wording or restructuring paragraphs.</li>
  177. <li><strong>Publishing</strong>. Fiddling with formatting, tuning WordPress, automating your
  178. git+hugo+heroku deployments.</li>
  179. <li><strong>Producing Figures</strong>. Sketching figures on paper or browsing the web for
  180. images that you can use in your presentation.</li>
  181. </ol>
  182. <p>Remember: <strong>The first milestone for your document is an outline. Everything that
  183. is not directly contributing to this goal is a distraction.</strong></p>
  184. <p>When you are happy with the outline, <strong>the second milestone is a fully fleshed
  185. out text, where all notes have been converted to paragraphs.</strong> The text should
  186. cover the intended content but does not need to be polished or well written.</p>
  187. <p>Once you are at this point, you start worrying about polish: Remove typos,
  188. improve wording, restructure paragraphs. Also work on figures and publishing can
  189. be delayed to this point without any problems.</p>
  190. <h3 id="make-your-text-skimable">Make your text skimable</h3>
  191. <p>According to <a href="https://www.towermarketing.net/blog/winning-the-fight-against-a-website-users-attention-span/">someone on the
  192. internet</a>:</p>
  193. <blockquote>
  194. <p>Eight seconds. A website user’s attention span lies somewhere around eight seconds.</p>
  195. </blockquote>
  196. <p>In these eight seconds, your document has to reveal enough value to the user,
  197. that he/she is willing to invest more time into actually reading the document.</p>
  198. <p>If you want your voice to be heard (and also improve the
  199. <a href="https://www.amazon.com/Dont-Make-Think-Revisited-Usability/dp/0321965515/ref=pd_sbs_sccl_1/142-5208579-0665727?pd_rd_w=IgY9h&amp;pf_rd_p=3676f086-9496-4fd7-8490-77cf7f43f846&amp;pf_rd_r=CGY8ZQY3T7ESSFA4W7RD&amp;pd_rd_r=a1baa3bd-3e30-402a-afe2-9d01086d2fc5&amp;pd_rd_wg=eMOQZ&amp;pd_rd_i=0321965515&amp;psc=1">usability</a>
  200. of your text) you have to design your document for “skim-ability”. You do this
  201. by providing anchor points that allow the user to gauge the content without
  202. actually reading it. You want the outline and key arguments to keep standing out
  203. in the final version of the document.</p>
  204. <p>Section Headings and Lists are the key anchor points you want to use to reach
  205. this goal. Also Figures, Quotes and Highlights are features that stand out and
  206. grab attention while skimming.</p>
  207. <blockquote>
  208. <p>If you are writing a slide-deck, a good approach to ensure skim-ability is the
  209. use of Action Titles. Action Titles are slide titles that summarize the content
  210. of a slide in a complete sentence. By doing this you allow the reader to get the
  211. gist of your document by just reading the titles. This highly annoying guy on
  212. the internet does a fine job of explaining the concept
  213. <a href="https://youtu.be/rSk11YqnXoc?t=131">here</a> and ideas around it.</p>
  214. </blockquote>
  215. <h3 id="provide-summary-sections">Provide Summary Sections</h3>
  216. <p>Summary sections are commonly found in document templates and academic writing.
  217. They are usability features, that provide a high-level overview about the
  218. content for readers in a hurry. Expect that a large fraction of your audience
  219. will only read a summary.</p>
  220. <ul>
  221. <li>
  222. <p><strong>Abstract</strong> / <strong>Executive Summary</strong> / <strong>TL;DR</strong>. This section summarizes the
  223. content of the document, deliberately duplicating information. It’s generally
  224. the first section of your document, and is intended for reader that has not
  225. yet read the document. A good abstract describes context, motivates the
  226. problem summarizes the findings but also leaves some suspension to motivate
  227. further reading.</p>
  228. </li>
  229. <li>
  230. <p><strong>Conclusion.</strong> This section also summarizes the content and is hence similar
  231. to an abstract. The difference is that it is the last section in your
  232. document, focuses on the outcomes and is deliberately referencing back to the
  233. content. The basic idea is that the reader had read the document before he/she
  234. arrives there, but this is in practice almost never the case.</p>
  235. </li>
  236. </ul>
  237. <p>It’s important to note that these summary sections are independent of the main
  238. story line, and are hence an artifact that can be prepared independently.
  239. Generally, I would recommend to start working on summary sections (like
  240. Abstract/Conclusion) last, since only then will you be certain what your
  241. document actually covers.</p>
  242. <h2 id="the-practice-of-writing">The Practice of Writing</h2>
  243. <h3 id="keep-writing">Keep Writing</h3>
  244. <p>The only way to improve your writing is by writing. As with practice in general,
  245. valuing quantity over quality is generally a good idea. Developing a writing
  246. muscle, and writing relatively short medium quality documents every week will
  247. make you a much better writer than crafting highly polished documents once a
  248. year.</p>
  249. <blockquote>
  250. <p>My English teacher in school used to say: “Writing. Only writing brings
  251. blessing.” I did not think much about this slogan, but it was catchy enough to
  252. stick with me. Now I consider it a deep truth, and keep it at the top of my
  253. blog, as a reminder.</p>
  254. </blockquote>
  255. <h3 id="leverage-small-writing-tasks-as-exercise">Leverage small writing tasks as exercise</h3>
  256. <p>Most of the rules that apply to writing long-form documents like Tech
  257. Narratives, Blog Posts or Papers hold up for writing short documents like
  258. E-Mails or issue tickets. Use this documents to practice your writing skills, by
  259. make them well structured, usable and polished.</p>
  260. <h3 id="get-early-feedback-on-your-outline">Get early feedback on your outline</h3>
  261. <p>Once you have constructed an outline and polished the story-line you are at a
  262. great place to get initial feedback on your document. This allows you to uncover
  263. flaws in your story-line early, and make sure you are on-target with the
  264. content. Also, reading an outline is a very quick thing to do, so it will not
  265. take a lot of effort for your reviewer to go through your text.</p>
  266. <p>This is most important for long documents, that you are producing on request of
  267. a stakeholder (manager).</p>
  268. <h3 id="circulate-drafts-of-the-text-to-the-selected-audience">Circulate drafts of the text to the selected audience</h3>
  269. <p>Once you fleshed out the content, and did a first editing pass removing the most
  270. glaring grammar and spelling mistakes, you are at a good point to sent the
  271. document to a few selected members of the target audience.</p>
  272. <p>This practice has three benefits:</p>
  273. <ol>
  274. <li>You will get a pair of fresh eyes on the text that will at the very least
  275. catch a few grammar quirks that remained in the text.</li>
  276. <li>You take a break from working on the text yourself, until you received the
  277. feedback, allowing yourself to take a fresh look at your writing.</li>
  278. <li>You have an excuse to reach out to old friends that you had neglected for far
  279. too long.</li>
  280. </ol>
  281. <p>Hint: Don’t forget to thank your reviewers in an “Acknowledgements” section.</p>
  282. <h1 id="acknowledgements">Acknowledgements</h1>
  283. <p>Thanks to my sister, Johanna Hartmann, and <a href="https://twitter.com/andrewhowdencom">Andrew
  284. Howden</a> for feedback on earlier versions of
  285. this document.</p>