https://zodvik.com/posts/on-writing-well/ Home > Posts > On Writing Well On Writing Well August 16, 2024 Share feedback here | HN discussion Writing a technical document is surprisingly hard. That is not because of the skill to tell a story. It's because writing forces a level of clarity that is easy to gloss over while thinking through a topic. Folks who take interviews for engineers will relate to this. The candidate talks through a solution. You can tell their approach doesn't work but the candidate doesn't see it. When you ask them to write the code, it helps them understand that what they thought doesn't pan out. The rest of the document is my collection of tips to write well. These are not mutually exclusive. 1. Write for your audience 2. Write simply 3. Remove weasel words 4. Apply the "So what? test 5. Add a structure 6. Be persuasive 7. Non-obsolete writing. These don't make the writing brilliant by any measure, but simply avoid the common pitfalls. Write for your audience Ask the below two questions before writing. Your document structure, degree of detail, and words you use can change depending on your audience. 1. Who am I writing this for? 2. What are the top 1-3 takeaways after someone's read? Once you're done, read the document from your audience's perspective and understand if the ideas come through. Let's say you're writing about updates & work done post an outage. What you write will vary depending on whether the audience is your team vs all of engineering vs an update for executives What to focus on What not to include How did we discover the issue? Things that folks on the Granular details of system team will already know Team characteristics during the outage the list of services, Granular details on a specific what do they do, etc. set of changes done Learnings Impact in terms of customer Architecture diagram, Executives experience Monetary impact call graphs, etc. Likelihood of repetition Jargons Write simply Use fewer than 30 words per sentence Longer sentences tend to increase cognitive load. Above a certain point, you forget how a sentence started by the time you came to the end of it. Use ordinary words and simple sentences A lot of your readers may not have English as their first language. They would've sufficient technical understanding to get the ideas, but fancy writing gets in their way. Remove fluff If you remove a phrase or a statement from a document and the meaning remains clear, remove it. Avoid jargon or acronyms Do not use terms that the audience may not be familiar with. If you necessarily have to, then explain those terms along with their usage. Before After As our company starts to diversify itself into more and more businesses in As our company expands into the transactional & financial services more financial services, it ecosystem, it has become imperative that needs to create reusable we build a host of central capabilities solutions that can be which can be used as a repository of applied across different solutions which can be redeployed and business areas. reused primarily in a business agnostic way. Given how we would often end up being As we become a key resource the conduit point for a host of future for many CxO's future building efforts for a lot of the CXOs, projects, we may face we may often end up in resource resource limitations, constrained zones and will end up in one leading to one of two of the following 2 scenarios. situations: Remove weasel words Replace adjectives with data or details. Whenever possible, add a link to the data along with it. Adjectives often mask relevant details that then require more back and forth to get to the same shared understanding. Before After We had a great quarter Our profitability went up by 15% this quarter to 115M. We often had this bug and it We had this bug 3 times in July impacted many clients. It's 2020 it impacted 301 users across urgent to fix it. 12 companies. Our DB size increased Our DB size increased 2x in the unexpectedly and is huge now last 3 months, instead of the usual 1.2x. All the customers were impacted 10,400 customers couldn't complete by a major issue, during this a purchase for 2h13m, due to a event. We lost a lot of money. server failure introduced by a code Hopefully, we fixed the main change, resulting in an estimated problem really quickly. loss of $50 000 (+/- 4%). Apply the "So what?" test Ask the "So what" question to every sentence that you write. For example, if you say "We built a new platform to run load tests". So what? How does it help me? Instead, we can Before After We built a new We built a new load test platform that lets anyone platform to run run load tests on demand, reducing the time to set load tests up from a day to 15 mins The "So what" test can also lead to completely deleting sentences that don't add any value to the document. It also forces us to quantify the impact in our narrative. Add a structure Structure in a document helps tell a story. A popular structure is SCR * Situation - frame the context * Complication - why the situation requires action * Resolution - the action to be taken More often than not, this can be templatized, as we do for PRDs, Architecture & Design documents, RCAs, etc. Two other common sections include * Asks -- If you have asks that you want your audience to approve or provide feedback on then just create a section called "Asks" and make your asks clear in plain English * Appendix -- Anyone who is interested to look at the details can refer to the appendix section but for everyone else, they stay on the crux of the document and don't get distracted by too many details. This also serves as the section to post references for data shared through the document. Be persuasive Prefer active voice to passive. Active voice tends to be concise and clearly identifies who performed the action. Before After The data center's efficiency was The new cooling system improved by 15% when a new cooling improved the data center's system was implemented efficiency by 15%. Don't ask for permission. For systems under your control, frame your writing as "we will do X" rather than "we would like to do X". This sounds more confident and surfaces alternative views faster. The latter is also ambiguous if the action will be taken or not. Non-obsolete writing Most docs are short-lived and used for point-in-time discussions. However, some documents serve for a longer time. To have your writing stand the test of time, avoid using references that change with time or location. Examples * Use absolute time units (Aug 28, 2024) instead of relative (in the next 2 weeks) * Do not write "the new office", instead name the office. * The degree for a temperature unit will be interpreted as Celsius in India but Fahrenheit in the US. In addition, add a section at the top of every document that covers who wrote it, when it was written, and who approved it (if required). This helps provide necessary context to the reader on how to interpret the rest of the document. Appendix * https://www.paulgraham.com/simply.html * https://x.com/destraynor/status/1258372157706510336?lang=en * https://aws.amazon.com/builders-library/ using-load-shedding-to-avoid-overload/ --------------------------------------------------------------------- - Migrating to 1Password --------------------------------------------------------------------- back to top Powered by Hugo and tomfran/typo