Document writing
I have been heads down writing a handful of documents for the past few weeks. I figured it would be beneficial to share my process for crafting these documents, as this is a fundamental skill we can all improve on. While there is an abundance of information available on technical writing, concrete examples are scarce. Although templates for different styles exist, they can often be restrictive. Although every document shares commonalities, every document is unique.
Journalism employs the concept of the inverted pyramid, which is a valuable technique to incorporate. The core aspect of the inverted pyramid is to prioritize the most newsworthy information, such as the who, what, when, and why, in the initial paragraphs. This is followed by delving into important details, and finally providing a smaller amount of general and background information. Regardless of whether an email, a one-pager, a six-pager, or any other document is being written, the inverted pyramid approach is highly recommended. Most training on writing techniques revolves around this fundamental principle. My documents tend to follow this pretty well, ~50% context expectations and background, ~35% important details (the meat of the document), ~15% deep dives into the meat.
A common pitfall I have observed in many engineering and even product management documents is the failure to adequately address the initial paragraphs. Some writers skim over the introduction and requirements, jumping straight into implementation details. It is crucial to remember the importance of focusing on the essential details first, don’t miss the forest for the trees. If the implementation specifics, such as the use of a lambda function for a particular task, are discussed prematurely without first establishing the requirements, the engineering choice may be rendered moot. By skipping the in-depth exploration of the “why” behind the document’s purpose, critical requirements can be overlooked. A lot of your reviewers, especially more senior reviewers, will only truly read the first and last page of your document - skimming the rest.
In the process of writing my latest design document, I went through three attempts at refining the format and content before even presenting it to another person. This iterative approach was necessary because, upon objective review, I found myself left with lingering questions and confusion. The recurring question that emerged was “why?” The “why” is the most crucial component of any document – why are you writing this document, and perhaps more importantly, why are you doing it now? While templates aim to provide guidance, especially for newer engineers or simpler tasks, they can also be a hindrance. Do not be afraid to deviate from a template by skipping sections or adding new ones as needed.
Alright, without further ado here is a rough set of how I write all of my documents. It does not matter what type of document I write, this is what I start with.
- Write an executive summary. Summarize the document’s purpose in 1-2 sentences, often starting with “The purpose of this document is to…” This may change, and that’s okay.
- Decide on the document format. Determine whether it’s a 1-pager, 6-pager, or something in between, and whether it’s a decision doc, information doc, design doc, etc.
- Brain dump unorganized bullet points. Jot down random thoughts and ideas over a few days without worrying about organization. These may be things another person has said or has come to your mind. A few examples:
- This specific algorithm is a core choice.
- The fundamental limitation of the existing system is XX.
- We have 2 realistic options and 2 unrealistic options.
- Person Y thinks we should talk about X
- Determine the target audience and their motivation. Identify who should read the document and why they would want to spend their valuable time reading it, including both the targeted audience (e.g., team X or person Y) and untargeted reviewers (people who will review but are not intended audience).
- Create diagrams. 90% of documents should have at least one picture. Start with a rough draft and refine later. Initially, create multiple diagrams and then combine or simplify them.
- Start organizing. Categorize your brain dump and diagrams into themes like background, design, options, tradeoffs, etc.
- Draft your conclusion. Determine what you want from the document, and if the conclusion has changed from the initial purpose, consider whether to restart or leverage your progress. Do you need to go back to any of the prior steps?
- Add context to support bullet points. Flesh out each section with additional information and context to make the bullet points more comprehensible. Important bullet points are normally repeated in multiple sections.
- Produce a rough draft. At this stage, the draft is typically 2-3 times over the target size due to bullet points and duplicate information. Convert your bullet points into narrative form, and consider using an LLM to assist with this step.
- Get feedback from a trusted source. A quick skim by someone you trust can help determine if you’re on the right track. They will also help act as a rubber duck because if you are confused trying to explain to them, you will be confused explaining to a reviewer.
- Cleanup and condense the document. Remove fluff and duplicate information, ensuring the document is dense but clear and concise, leveraging the reader’s intelligence. Do not explain trivial concepts in great details, but also do not be afraid to spend time on those difficult concepts.
- Sleep on it. You cannot write a good document in a day. Sleep on it and reread it. Print the document out and read it out loud. It sounds silly but when you read something out loud you activate a different part of your brain which will allow you to catch confusing grammar and confusing sections.
- Iterate as needed. At every step, decide if you need to revisit a previous point. Maintain a “things missed” list, and merge missed items back into the document as a group when there are enough. You should be rewriting sections of your document a minimum of 2-3 times.