The Ultimate Guide To Writing Technical Reports

Post by
Kyle O'Shea
The Ultimate Guide To Writing Technical Reports

Data exploration and analytics are only the beginning— the real business impact comes from the ability to communicate your results.

At Kyso we’re building a central knowledge hub where data scientists can post reports so everyone — and we mean absolutely everyone — can learn from them and apply these insights to their respective roles across the entire organisation. We render tools used by the data team in a way that is understandable to all, thus bridging the gap between the technical stakeholders and the rest of the company.

But while we provide a space for data engineers, scientists and analysts to post their reports and circulate internally, whether these reports will be turned into business actions depends on the how the generated insights are presented and communicated to readers. Any data team can create an analytics report, but not all are creating actionable reports.

This article will discuss the most important objectives of any data analytics report and take you through some of our most vital tips to remember when writing up each report.

Reporting Objectives

The final goal of any data exploration & analysis is not to generate interesting but arbitrary information from the company’s data — it is to uncover actionable insights, communicated effectively in reports that are ready to be used around the business to take more data-informed decisions.

To achieve this, there are three underlying guidelines to follow and to continuously refer back to when writing up data-based reports:

  • Intent: This is your overall goal for the project, the reason you are doing the analysis and should signal how you expect the analysis to contribute to decision-making.
  • Objectives: The objectives are the specific steps you are taking or have taken to achieve your above goal. These should likely form the report’s table of contents.
  • Impact: The result of your analysis has to be usable — it must offer solutions to the problems that led to the analysis, to impact business actions. Any information which won’t trigger action, no matter how small, is useless.

Now let’s dive into the details — how to actually structure & write the final report that will be shared across the business, to be consumed by both technical and non-technical audiences alike.

Structuring the Report

As with any other type of content, your reports should follow a specific structure, which will help the reader frame the report’s contents & thus facilitate an easier read. The structure should look something like:

  • Introduction: Every report needs a strong introduction. This is where you intro the reader to the project, the reasons for carrying out the analysis & what you expect to achieve by doing so. This should also be where you lay out the table of contents.
  • Methodology: This does not need to be technical. Simply describe the data you are using and the types of analyses you have conducted & why.
  • Results: This is the main body of the report, and likely split into sections according to the various business questions the report attempts to answer & the results generated for each question.
  • Decision Recommendations: Ok, so you have completed the project, run the analyses & generated your results. What are the recommended business actions based on these insights? Be objective.
  • Conclusion: Tie the entire report up (in a single paragraph if possible), from the starting objective of the project to the recommended decision outcomes. In this final section you can add your own personal touch — what the results mean from your perspective & perhaps your recommendations for future analyses on the subject.

Writing the Report

1. Consider your target audience

Who is your report intended for? If it’s for a sales lead, emphasise the core metrics by which their department evaluates performance. If it is for a C-level executive, it’s generally best to present the business highlights rather than pages of tables and figures.

Keep in mind the reason they have requested the report & try not to stray from that reason.

2. Have a clear objective

As mentioned already, explain clearly at the beginning what you’re article is going to be about and the data you are using. Provide some background to the topic in question if necessary & explain why you are writing the post.

3. Structure your writing

Determine the logical structure of your argument. Have a beginning, middle, and end. Provide a table of contents, use headings and subheadings accordingly, which gives readers an overview and will help orientate them as they read through the post — this is particularly important if your content is complex.

Aim for a logical flow throughout, with appropriate sections, paragraphs, and sentences. Keep sentences short and straight-forward. It’s best to address only one concept in each paragraph, which can involve the main insight with supporting information, such that the reader’s attention is immediately focused on what is most important.

Never introduce something into the conclusion that was not analysed or discussed earlier in the report.

4. Start strong

Writing a strong introduction makes it is easier to keep the report well structured. Your introduction should lay out the objective, problem definition and the methods employed.

A strong introduction will also captivate the reader’s attention and entice them to read further.

5. Be objective

The facts and figures in your report should speak for themselves without the need for any exaggeration. Keep the language as clear and concise as possible.

An objective style helps you keep the insights you’ve uncovered at the centre of the argument.

6. Don’t overdo it

It is always best to keep your report as clear and concise as possible. By including more information that, while useful, is unnecessary to the core objectives of the report, your most central arguments will be lost.

If absolutely necessary, attach a supporting appendix, or you can even publish a series, with each report having its own core objective.

7. Plotting libraries

Interactive python plotting libraries in python
Interactive plotting libraries — Altair, Plotly & Bokeh

There are many visualisation tools available to you. For static plotting or for very unique or customised plots, where you may need to build your own solution, matplotlib and seaborn are your answers.

However, if you really want to tell a story and allow the reader to immerse themselves in your analysis, interactivity is the way to go. Your two main options are Bokeh and plotly. Both are really powerful declarative libraries and worth considering.

Regardless of the one you choose, we recommend picking the one library and sticking with it until there’s a compelling reason to switch.

Altair is another (newer) declarative, lightweight, plotting library, and merits consideration. Check out its gallery here.

While Plotly has become the leader for interactive visualizations, because it stores the data for each plot generated in the user’s browser session and renders every interactive data point, it can really slow down the load time of your report if you are working with multiple plots or with a very large dataset, which negatively impacts the reader’s experience.

If you are generating a lot of graphs or are working with very large datasets but wish to retain the interactivity, use Bokeh or Altair instead.

8. Avoid overuse of graphics

Charts, graphs and tables are a great way of summarising data into easy-to-remember visuals. Try not to break-up the flow of the report with too many graphics that essentially show the same thing. Pick the chart, graph or table that best fits with the paragraph and move on to the next point.

9. Document your charts!!!

When plotting make sure to have explanatory text above or below the chart — explain to the reader what they are looking at, and walk them through the insights and conclusions drawn from each visualisation.

Kyso report with undocumented charts
No graph heading, no legend or y-axis title.

Label everything in your graphs, including axes and colour scales. Create a legend if necessary.

Kyso report with documented charts
The difference good documentation makes!

10. Hide your code

When writing a report that is intended to be consumed by non-technical business agents throughout the organisation, hide your code. How you generated your graphs is not important for these users, only the visuals and the insights they display are.

Kyso report with code hiden
Code Hidden.

Naturally, if you are writing a guide or a particularly technical post for your fellow data scientists and analysts, in which you are constantly referring to the code, you should show it by default.

Kyso report with code shown
Code Shown.

Final Thoughts

And there we have it! 10 tips to follow every time you are writing up a data-based report. A note on the conclusion — don’t just taper off at the end of the article or finish with the final point in the main body. Give the reader a quick summary of what they have learned, explain how the insights gained impact for the business and how they can apply this knowledge in their work.

Be sure to also make your analysis reproducible for your fellow creators throughout the company — it’s always a good idea to follow coding best practices when developing a data science project or publishing research, including using the correct directory structure, syntax, explanatory text (or comments in the code cells), versioning, and, most importantly, making sure all relevant files and datasets are attached to the post. Have a call to action — perhaps a recommendation for extending the analysis.

And finally, last but certainly not least, add an appropriate title, description, tags, and preview image. This is important for organising the team’s work on whichever curation system you are using — presentation is key.

Related Articles