Established onExcel 365: threaded comments need vendor storageExcel 2016 and later: notes travel with the fileGoogle Sheets, web: notes and comments, both attached to cells
A workbook that somebody else has to use needs four things written down, and none of them is what the formulas do.
The four
What it is for. One paragraph: what question this file answers and for whom. Files outlive their purpose and are then used for the purpose somebody assumes.
Where each input comes from. Per input: the system, the report, the person, or the policy. This is the question that gets asked most and answered least.
How to refresh it. The sequence somebody must perform to bring it up to date, in order. If that sequence is a stored query, say so and name it.
What it does not cover. The exclusions, the simplifications and the known limitations. A model that excludes one region is correct until somebody uses it for a question about that region.
Where not to put it
In cell comments. They are hidden by default, they do not print, they are absent from every export, they are deleted with the cell they attach to, and in one of the two products the threaded kind requires the file to be on the vendor's storage to exist at all.
A comment is a good place for a remark about one cell and a bad place for anything a reader needs.
Where to put it
On a sheet, first in the tab order, called something obvious. Plain text in cells, one topic per row, no merged cells and no formatting that matters.
It prints, it exports, it is visible to anybody who opens the file, and it cannot be deleted by an operation on the data.
What not to write
Descriptions of what formulas do. The formula is there and says it better, and a prose description of it decays the moment somebody edits the formula and not the prose.
Write the things a formula cannot contain: why the decision was made, what was considered and rejected, where the number came from, and what happens next.
The change log
A block at the bottom of the documentation sheet: date, person, what changed, why. Four columns, appended to, never rewritten.
This is the description that the version history described in the first part of this site cannot record. It costs a line per change and it is the only thing that makes a version list usable a year later.
The documentation that does not decay
Prose decays because nothing forces it to be updated. Structure does not, which is why most of the recommendations on this site are arrangements rather than notes.
An input row labelled with its units and its source is documentation that cannot drift from the value, because it sits beside it and is read every time somebody changes it. A note on another sheet saying the same thing can be wrong for a year without anybody noticing.
So write the sheet, and prefer to encode anything you can into the layout instead.
The as-of date
One cell, near the top, stating the date the data represents, set deliberately rather than computed. Every report produced from the file should show it.
This single cell prevents the most common misunderstanding in circulated spreadsheets, which is somebody acting on a figure without knowing how old it is.
Naming the file
The file name is documentation that everybody reads, and it is where the copy problem in the next part begins. A name that carries the content and the as-of date, and nothing about the version, is the arrangement that survives contact with electronic mail.
What we cannot verify
The behaviour of notes and threaded comments, including the storage requirement for the threaded kind, is documented by the vendors and was confirmed on current builds. The rest of this entry is a recommendation about practice rather than a claim about software, and it reflects the same modelling standards referred to elsewhere in this part.
Who owns the file
A name and a date, in a cell. Not a team, a person.
Every file eventually raises a question that only one person can answer, and a workbook circulating without an owner is one where that question goes to whoever sent it last, who did not write it. The cost of naming an owner is that they must be told, which is the point.
Where the sheet should sit
First tab, always. A documentation sheet placed last is a documentation sheet nobody has read, because the file opens on whichever sheet was active when it was saved and people navigate rightwards from there.
In short
- Write what it is for, where each input comes from, how to refresh it, and what it excludes.
- Do not put any of it in cell comments, which are hidden, unprinted and deleted with the cell.
- Put it on a sheet, first in the tab order, in plain cells.
- Do not describe what formulas do; write what a formula cannot contain.
- A four-column change log is the description the version history cannot record.
- Prefer structure to prose, because prose decays and an labelled input row cannot.