top of page
  • Writer's pictureKelly Adams

Importance of Documentation as a Data Analyst

A pile of documents sitting on a table

Documentation is a vital but it’s not talked about as much compared to the main analytical tools like SQL. I spend a lot more of my time documenting than I’d like to be honest. While it’s not a lot of fun it’s a necessary task for data analysts. In this article I go into what I document, the tools I use to document, why it’s important and how to practice documentation. 

What Do I Document 

What an analyst documents varies from job-to-job. But there’s an element of documentation whether it’s documenting queries or the different dashboards. Since, I’m the main data analyst at my company I do almost all of the documentation regarding analytics. Below is what I document:

  • Reports - Detailing the purpose and specific metric definitions.

  • Tables - Describing how an entry is made and explain the columns, and often there’s a data dictionary.

  • Queries - Explaining what each query returns, specific notes or definitions. I add comments to my query. Multi-line in the beginning to explain the query and any specific notes or definitions used.

  • Projects - My personal notes on each project. It includes: what I tried, what worked and what didn't, etc, the detailed request, and any other notes I find relevant.

Tools I Use

The tools that an analyst use also widely vary. Especially if your company has specific tools/software used for documentation. Below is what my company uses:

  • Confluence - For more text heavy documentation (e.g. table definitions). There are other tools like Google Docs or OneDrive to share files. 

  • Documents - For my personal project notes. I use markdown files (saved locally on my machine) and use the PARA method for my file management. 

  • Git/Github - For the queries. This lets me track changes and look at the history of the queries. It’s vital for our analytics, especially when integrating queries in BigQuery.

Why is Documentation Is Important

Documentation isn’t a fun topic but without it, life is frustrating. . It’s hard to understand what’s going on, what has been done, and you’re generally feeling lost. Below are a few reasons why documentation is important:

  • Future proof: Helps future me understand why I did XYZ or what specific definition we used.

  • Save time: It eliminates guesswork and trying to figure out what a definition in a table is or what method we tried already.

  • Communication: Ensures that the reasoning behind the queries, codes, projects, is easily understandable for everyone.

How to Practice

Documentation should be part of your workflow, regardless if you’re an “aspiring” analyst or a full-time one. Here are some ways to practice it:

  • Commenting on your code to make it easily understandable (by you or for someone else). 

  • Taking detailed notes on projects you’re working on, then you can reference it easily later to talk about it. 

  • Write an article or blog post about your project, this lets you summarize and communicate your findings.

Other Tips

Effective documentation needs to balance detail with clarity. Here are a few best practices in mind:

  • Make it future-proof and easy to understand for others to read. Not just yourself.

  • Use templates to speed up documentation process.

  • When you make changes, document it. As soon as possible so you don’t forget it.


Documentation is essential, but not the most thrilling part of our job. It’s the backbone of insightful and efficient data analysis. The key is maintaining and keeping it up to date. It’s important to be consistent about it and learn how to integrate it into your routines. A well documented analysis could be the difference between starting off an analysis strong and wasting time trying to understand an old query.


bottom of page