Reading a Writing Heatmap: What the Colours Mean
Take one week of writing: 350 words on Monday, 540 on Tuesday, 700 on Wednesday, 820 on Thursday, and 3,500 on Friday, when a free afternoon finally let the chapter run. Put those five days into a heatmap, and what you see depends less on the words than on a setting inside the app.
| Day | Words | Step, equal slices | Step, by distribution |
|---|---|---|---|
| Monday | 350 | 1 | 1 |
| Tuesday | 540 | 1 | 2 |
| Wednesday | 700 | 1 | 3 |
| Thursday | 820 | 1 | 4 |
| Friday | 3,500 | 4 | 4 |
Why the same week gives two pictures
Some apps cut the range from zero up to your best day into equal slices. The d3 visualisation library calls this scaleQuantize and documents it as dividing the input domain into uniform segments (d3-scale). With four steps and Friday as the best day, the cut points fall at 875, 1,750 and 2,625 words, so Monday to Thursday all end up in the lightest step and Friday is the only dark square.
Other apps set the cut points by distribution, so that each step holds roughly the same number of days. In d3 that is scaleQuantile (d3-scale). For this week the cuts land at 540, 700 and 820, so the squares get darker from Monday to Thursday, and Friday shares the darkest step with Thursday.
Equal slices also have a long memory. For as long as that Friday stays inside the rolling year, every ordinary day is measured against it and stays pale. Comparing your shades with another writer’s grid tells you little for the same reason, and comparing this year’s grid with last year’s is not much better, since the reference point moved the moment your best day changed.
Most apps offer four or five steps plus empty. Stephen Few puts the practical ceiling for a dense grid at eight, beyond which neighbouring shades stop being separable (Perceptual Edge, 2017), so a small number of steps is a reasonable choice. It just means each shade covers a wide band of word counts.
What the position tells you
The layout comes from software development. GitHub introduced its contribution calendar on 7 January 2013 to show “how frequently you’ve been contributing over the past year” (GitHub Blog), and it counted commits, which on most days are small whole numbers. Word counts spread over a far wider range, so on a writing heatmap the colour says less than it appears to.
The position is a different matter. Columns are weeks and rows are weekdays, and because 365 days don’t divide evenly into weeks, a full year takes 53 columns, which makes 371 squares with six of them left empty. Whether a square is filled at all is recorded exactly, and that is where the useful patterns are.
Three patterns in the empty squares
Blank squares tend to fall into three patterns that you can tell apart by eye.
Stripes. A whole row stays blank because you never write on that weekday. Often this just reflects how your week is organised: a blank row of Sundays usually means you decided long ago to keep that day free. A blank row of Wednesdays is more often something nobody ever decided, and it can be worth checking what regularly happens on Wednesdays instead.
Blocks. Two or three blank columns next to each other, typically from a holiday or an illness, sometimes from a deadline at work. They look dramatic in the grid but rarely say much about your routine, because their cause lies outside the writing.
Fraying. Over several weeks, the boundary between the dense part of the grid and the patchy part moves. First one day a week goes missing, then two, until only Sunday is left. Of the three patterns this is the one worth worrying about, and a streak counter can’t show it, because the counter drops to zero on the first missed day and has nothing further to report after that. When a streak is still useful is covered in the piece on writing streaks.
How many gaps a normal year contains
Before you read meaning into a blank patch, work out how many such patches chance alone would give you. Assume four writing days out of seven, and treat the days as independent:
A given day is blank with a probability of 3/7, about 43 per cent.
Five blank days in a row come to 3/7 to the fifth power, roughly 1.4 per cent.
A year contains 361 five-day windows, so you can expect about five completely blank five-day stretches.
For a full week without writing, the same calculation gives about one a year.
At four days a week, then, losing an entire week happens roughly once a year and on its own is no sign that anything has gone wrong. Real writing days are not independent, of course: they cluster, illness and holidays come in runs, and a session yesterday makes one today more likely. Read the figures as an order of magnitude.
That order of magnitude is worth having because intuition about chance fails in a known direction. People expect random sequences to alternate more often than they actually do and treat long runs as something that needs explaining; Maya Bar-Hillel and Willem Wagenaar reviewed the research on this in 1991 (Advances in Applied Mathematics 12, issue 4, pages 428 to 454). On a grid of 371 squares, the pale patch that catches your eye may well be one the grid was bound to contain anyway.
Three places the grid points the wrong way
Revision days. An afternoon spent cutting 400 words and rearranging the rest shows up as a blank or nearly blank square. The grid measures the product while you worked on the text. Which unit fits which phase is the subject of words, hours or pages.
Green on green. Red-green colour deficiency affects about 8 per cent of men and about 0.4 per cent of women of European descent (Birch, Journal of the Optical Society of America A, 2012). Four greens that differ only in hue are not a scale for those readers. A usable heatmap needs a real lightness difference between steps, and a number when you tap a square. GitHub added keyboard navigation and a spoken announcement per cell in 2023, in the form “11 contributions on Monday, February 21, 2022” (GitHub Changelog). The picture alone was not enough.
Zero days with real work in them. Research, outlining, reading, a synopsis. All of it belongs to the project and none of it adds words. Count those as failures and you have built a scoreboard that punishes thinking. Which tools can record that kind of day at all is compared in the five ways to track writing progress.
A five-minute read-through
Count the filled squares in the last eight weeks, then in the eight weeks before that. Two numbers. They tell you more than any reading of the shades.
Go down the seven rows and count per weekday. Your weakest weekday is the best place to change something, because that is where a small change moves the most.
Find the longest gap and check what was in your calendar. A cause means it was a block. No cause means it was fraying.
Tap your darkest square and read the number. If it sits far above your normal day, you now know why the rest of the year looks washed out.
Then stop looking at the shades. Everything after this needs numbers.
If you want to turn that into a daily target, the arithmetic is in how many words a day. If you are still deciding whether a tool is worth it at all, start with what a writing tracker is.
How many colour steps should a heatmap have?
Four to six plus empty is a sensible range. With fewer the picture gets coarse, and with more the neighbouring shades become hard to tell apart at the size these squares are usually drawn. The number matters less than whether the steps differ in lightness as well as in hue, because only then does the scale still work in a greyscale printout or for a reader with a colour vision deficiency.
Does a 20-word day count as a writing day?
As far as the grid is concerned it does, which is one of its weaknesses. A one-line note colours the square just like a proper session, only in a paler shade. If that skews how you read your own grid, pick a minimum for yourself and treat anything below it as a note rather than a writing day. Where that minimum sits depends on your practice, and it is something you decide yourself.
What happens to words I write after midnight?
That depends on where your app puts the boundary between days. Some book everything by calendar date, while others move the boundary into the early morning so that a late session still counts towards the previous day. It is worth testing this once and noting the result, otherwise you may later puzzle over gaps that come from nothing more than a booking rule.
Can I build a heatmap in a spreadsheet?
Yes. A date column, a word count column and a conditional format with a colour scale. Excel shades cells “with gradations of two or three colors that correspond to minimum, midpoint, and maximum thresholds” (Microsoft Support). That is the same relative scale the apps use, with the same outlier problem.
Heatmap or streak counter?
They show the same material at different resolutions. A streak is a verdict on today and resets to zero on a miss. A heatmap keeps the whole year and shows slow drift, which a streak cannot represent at all. Early in building a habit the streak does more work, later the grid does. The 30-day plan breaks the chain on purpose in its final week, so you find out how you come back from a gap.
Take five minutes with your own grid, but count only two things, the filled squares in the last eight weeks and the filled squares in the eight before. If the older number is clearly the bigger one, you have found this week’s problem, and no shade of green would have told you.