Stop 13 · Version Control, Git & CollaborationTopics · 4/7

Documentation Best Practices

In short

The person most likely to need your documentation is you, three months from now, wondering why a query excludes 2% of users. Good notes save hours and stop wrong numbers from spreading.

Writing down what a query does, why a metric is defined the way it is, and where data comes from — so the next person (often future-you) doesn't have to reverse-engineer it.

The jaadu sticks a blank card onto a fridge with a magnet, holding a pencil.

Think of it like this

The note on the fridge

When Mummy goes to Nani's for a week, she leaves a note on the fridge: which dabba has sugar, when the milkman comes, which tablet Papa takes. Short, clear, exactly what's needed. Documentation is that fridge note for your data work.

Watch it happen

What a good project README covers

README

Why it exists

Data sources

Definitions

How to run

Owner, updated

1/5Every project folder or dashboard gets one README. Start short and grow it.

The big ideas

What you need to know

Define every metric

"Active user = opened the app at least once in 7 days, excluding staff accounts." Write that down once.

Comment the why, not the what

"-- exclude refunds" is obvious. "-- refunds handled in finance report" explains a decision.

Date and own it

Every doc should say who owns it and when it was last checked. Stale docs are worse than none.

Keep docs next to the work

A README in the same repo or a description on the dashboard gets read. A doc hidden in some drive doesn't.

See it in code

Walk through the code

sql

1-- Name:    weekly_active_users.sql2-- Owner:   Priya, analytics team3-- Purpose: WAU for the growth dashboard4-- Grain:   one row per week5-- Active:  at least one 'app_open' event in the week6-- Excludes test accounts (is_internal = TRUE)7-- Last checked: 2026-10-208SELECT DATE_TRUNC('week', event_time) AS week,9       COUNT(DISTINCT user_id) AS wau10FROM events11WHERE event_name = 'app_open'12  AND NOT is_internal13GROUP BY 1;

1/4Name, owner and purpose tell readers whether this is the query they need.

A header block that answers the questions people ask most: who owns this, what does it count, and what's left out.

Save yourself the pain

Common mistakes

Oops

Writing a 20-page document nobody will ever update.

Do this instead

Keep a short README and metric definitions, and update them whenever the logic changes.

Oops

Leaving filters like "WHERE city_id <> 7" with no explanation.

Do this instead

Add a one-line comment on why, like "-- city 7 is the internal test city".

Your mission

Document one past query

~20 min

Quick check

Which comment is most useful in a SQL query?

Go deeper

1Add a comment header to your last 3 SQL scripts explaining their purpose.
2Start a simple metrics glossary defining your team's key terms consistently.
3Learn to document assumptions, not just steps — the 'why', not just the 'what'.