Reports are our chief vehicle for influencing organizations, especially as they grow to a larger number of people. Further, they are also how we assemble our collective knowledge about the problems we work on and the solutions to these problems. Because reports are so important, we’ve collected some guidelines about how to create amazing reports. This document is a prioritized list of the guidelines we’ve developed at LiveRamp. As always, no hard rules; ignore guidelines when you judge appropriate.
Put the Most Important Things First
We want to hook the reader as soon as possible by giving them the high-level overview of the important things covered in the report. We should strive to give our stakeholders all the key high-level information they need on the first page. Starting with a summary or abstract section is a great way to accomplish this. Similarly, low priority parts of the report belong in an appendix.
Strive for Brevity
Everyone is busy and we need to guard our time. This includes skipping verbose docs.
Publish Small Reports Frequently
A great way to keep reports short is to publish small amounts of work regularly. We can always write a review report to summarize key results from several related reports. This is also a great way to stay relevant in the minds of stakeholders. If they spend some time each week reading our reports then our projects will stay fresh in their minds.
Get and Give Feedback
It can be really helpful to get a second opinion. Your reviewers can let you know which parts are unclear and suggest improvements. We should encourage our stakeholders and other readers to give us such feedback so we can tailor our reports to meet their needs.
Have Fun
Reports can be a great place to include short jokes and have a little fun. Maybe there’s a meme or cartoon that makes a funny point related to your work. Keep it short, light, playful, and of course work appropriate.
Name Things Well
We commonly introduce new concepts and metrics within our work and we should think a little bit about how to name them. Names can stick so we want to start with a good name and poor naming can cause confusion. Favor longer and more descriptive names because we can always abbreviate them or create nicknames. Always define an acronym the first time you use it in a report.
Highlight and Define the Most Important Concepts/Metrics
Having the key terms clearly explained in an obvious place makes it much easier for the reader to understand the gist of the report.
Have an Optional Background and Introduction Section
At times people not familiar with our work will come across one of our reports and we should help them read the report by giving them relevant background. This is also important for framing a problem space so that our stakeholders know how we think about it and can ensure that’s consistent with their understanding. Great if you can link to another report or other doc that provides related background, because then you can make your background section even shorter.
Link Copiously
Whenever possible link to related past work or online materials (e.g., Wikipedia). This allows the reader to learn more if they choose. Particularly important when we mention past results so the reader can go back and review them when needed.
We also want to link to Jupyter notebooks and git repos for analyses and code so that people who work on a related project in the future can find and use these assets. Further, important if we ever need to go back and debug past results that appear inconsistent with new results. Also can be useful to link to JIRA epics/tickets or Trello cards related to this work.
Quantify and Compare
At times our results are quantitative and we want to communicate the main numbers to the readers. Our goal is to get a few key numbers to stick in our reader’s head and therefore influence how they think about the topic. In explaining quantitative results, it can be useful to compare against a baseline case. E.g., “data matches increase by a relative 20% from a median of 50% to 60%.” We want that “20%” stuck in their head like a catchy jingle.
Think of Reports as the Team’s Marketing Materials
Reports are how we get our team’s ideas out into the broader org. For many people, it’ll be their main interaction with our team. Go the extra mile and take an extra hour or two to really revise and polish any report. Create snazzy diagrams when appropriate and generate sharp figures and tables. You never know who may one day come across your report.
Practice, Practice, Practice
Technical writing is a skill and it takes time to develop. Always look for new opportunities to write. (E.g., company blog.) Get feedback and challenge yourself to improve specific parts of your writing in new reports.
Discuss Methods at a High-Level
We want to document how we solved a problem, but many of our readers won’t care much about the details. When there are important details to document, place them in an appendix.
As Much as Possible, Figures Should Stand Alone
We want to label and title figures and tables well enough that they can be understood without the extra context of the report. This allows readers to scan the report and quickly find the results they’re looking for. (You yourself may be such reader when you need to find your past results.) It also allows readers to directly share figures over email and slack, further spreading our work.
Develop Your Own Unique Writing Voice and Style
Higher priority than order would imply, but I’d like to end on this point.
Two people could write very different reports for the same project, and both reports could still be high quality. Some writers like short sentences. Other like to include longer sentences — with more complicated grammar structures — so as to concisely combine together as many points as possible. Use your own voice. You’ll have your own style for generating figures and tables. Don’t worry about copying others’ voice