On writing better documents
On writing better documents
A simple framework to get your point across, get faster alignment, and write memorable documents at work
Well written internal documents give you great leverage - it is easier to get your point across, get faster alignment, and act as a store of knowledge. Since working asynchronously is the norm now, writing clear internal communication saves countless hours that were once spent in meetings and scheduling.
In this note, we discuss a framework on how to compose good documents like memos for new initiatives, product requirement documents for your next feature or documentation of the latest release. The documents which help move things forward with your organization.
To make it more actionable, this framework is divided into three parts,
Before you write
While writing
After you write
Before you write
Make a table of everything
A concept I borrowed from a creative writing teacher, the table of everything is a n x n matrix where you dump all your thoughts in a random order that forces you to think non-linearly.
The trouble I have with lists is that lists force you to think linearly. Your current idea is connected to the previous one and the previous one with the one before. Lists and linear thinking make finding interesting patterns difficult.
A table of everything helps you collect all your thoughts in one place, establishes the scope and makes connections between ideas that were invisible before.
As illustrated below, fill each cell of the grid in random order with all the ideas you would want to present in your document.
Use the table you have filled as the reference when you start writing to build your narrative.
Define your audience
Once you know what to write, it is helpful to actively define your audience.
If your document is intended for your team, you can leverage the shared understanding of a topic. This helps you get to your core message quickly.
Defining your audience would also help you structure your document differently for different cohorts. A strategy document intended for your leadership team would be designed differently compared to the execution plan you share with your engineering team.
Within the same document that has readers across cohorts, you might add an executive summary if the audience includes your CEO and a section directed specifically to your analytics team if there is a need for it.
Work backwards
Define the key takeaways of the document and work backwards to develop a plan for how you would bring the reader to the same conclusion as you. This is arguably the most important part of the process.
Design a narrative structure
Record yourself narrating the ideas and read the transcript/listen to the audio. While recording, be kind to yourself and allow your mind to jump from topic to topic. This is the most natural way to establish connections and build a compelling flow of ideas.
This exercise will help you understand the flow of your document even before you get started.
Write a ghost document
A neat process that my friend, Vibhav Katre follows over at Clear is writing a ghost document, a practice common in the world of consulting. This is especially useful to gain alignment with a manager or the team before you start writing.
Once you have the narrative structure in place, create a ghost document (a skeleton of your document) with key points written under each section.
Once the structure is reviewed by your manager or a stakeholder, you can proceed to flesh it out. This helps in reducing the number of iterations and prevents surprises that arise from miscommunication.
While writing
Context is everything
The trickiest part of writing any document or presentation that is intended for your team is the assumption that everyone has the same amount of context. The audience has multiple threads running in parallel and it is your job to set the context and help them focus on your message.
Instead of jumping directly into the details, spend the first few lines answering the ‘why’ of the document. Establish the universe within which the document operates.
Keep it crisp
Good writing is clear thinking made visible.
Source: Unknown
When you make it crisp, the message reaches faster and with little ambiguity.
A point to consider is, ‘keeping it crisp’ does not mean writing dry, soulless essays. As you write consistently, your wit, your humour, and your personality come through - making the reading experience memorable.
Use visuals wherever required
The written word might not be the best carrier for all the ideas you would want to communicate. Especially for a new feature or design documentation, it is always a great idea to add a flowchart, wireframes (hand-drawn or digital) to help get your message across. In the end, the goal is to deliver clarity, so don't shy away from using visual aids.
Repeat and summarise key ideas
There are legitimate cases where your document has to run long and even after 1000 rounds of editing, it runs a mile long. In such cases, it's very easy to label the document as boring and reading it becomes a chore. This comes at a cost of the reader losing focus and missing key ideas.
In such cases, it is always a good idea to repeat your key ideas periodically.
Adding a summary or a TLDR section is a great idea, especially for documents that are designed to be revisited multiple times (think PRDs, Knowledge base articles)
An effective trick to get better at identifying the points to repeat and summarise is to ask yourself the question - "If I was the reader, which sentences would I highlight or make a note of?". This deliberate attempt at role-playing as the reader helps you empathise and also helps you see the gaps in your narrative.
Next steps
“You have made your point, delivered your message, great! What’s next?”
It’s very common to find strategy docs, memos or PRDs missing probably the most important part - the actionable items.
It is always a good idea to dedicate space towards the end to discuss the next steps, guide the reader instead of leaving them hanging or awaiting further instructions. It is very common to discuss these items over email or Slack and you very well know how easy it is for key decisions to be lost in all that clutter. Having a dedicated space within your document saves your time and your team’s.
After you write
Edit, edit, edit
Be ruthless, remove any part of the note that is not delivering any value. It is very easy to overthink and write long paragraphs to demonstrate the depths of your understanding.
Stick to the objective and have the confidence to remove unnecessary lines.
Format properly
A great document is not just great writing but also has great structure. Documents that are structured well are an outcome of the writer’s clarity. Good formatting can make a document look beautiful and polished.
To ensure the right hierarchy of information, generate a table of content (Google Docs and Notion have shortcuts for this) and verify if the section headers and dividers are used correctly.
Get feedback
Develop a trusted group of reviewers within the team who help you with the right feedback to improve your document. Having a fresh set of eyes review your document helps you verify if your writing is indeed clear enough.
Add an appendix
Depending on your document’s audience and purpose, an appendix might come in handy to the reader.
“An appendix contains supplementary material that is not an essential part of the text itself but which may be helpful in providing a more comprehensive understanding of the research problem or it is information that is too cumbersome to be included in the body of the paper”
Source: https://libguides.usc.edu/writingguide/appendices
Add an FAQ section
Leave an open section for questions that the reader might come up with during/after reading your document. The best documents anticipate the common questions (with answers) and seed them before sharing.
Sample questions might look like this - “How would you onboard existing users?”, “Where can I find the task list for milestone 1?” etc.
In addition to the above points, while sharing your document over email/Slack, communicate the expectations clearly and involve all the relevant stakeholders in the message chain. Over-communication doesn't hurt.
Good writing is deliberate. Good writing is an outcome of practice. The above framework is the outcome of writing, reading, and reviewing countless documents.
At first, it might be overwhelming to follow all the steps, but as you keep writing, you would develop your own framework and your own process.
To recap
Good internal documents help communicate ideas, bring clarity, and act as a store of knowledge within your organisation
Before you write - make a table of everything, define your audience, and work backwards
While writing - focus on establishing the context, keep things crisp, and repeat key ideas
After you write - edit ruthlessly, format your document well and leave room for questions
And finally, be kind to yourself. To become proficient, develop your own process and frameworks, standardise templates for repetitive writing tasks.
If you have any feedback, questions or just want to discuss anything — feel free to tweet at / DM me on Twitter or Telegram.
Thanks to Vibhav Katre who helped surface a few key ideas and to Akshay Kore and Saumya Kedia for editing it.