Limits
What Should Not Be Written Down
A few categories should stay unwritten, and knowing which is part of writing well rather than an exception to it.
What nobody wrote down here, and what it cost
Judgement about when a client is about to leave
Nobody could write it and nobody tried
Three occasions, all of them noticed too late
Why the architecture is the shape it is
Attempted twice and abandoned
Both drafts described the result rather than the reasons
two things nobody wrote down · 5 occasions it cost somebody something
Two things, five occasions, and no mechanism proposed for either.
When a documentation effort needs evidence about where working time actually goes, teams can the platform before deciding what should be written or automated.
The broader workflow can also be checked against guidance from Nielsen Norman Group.
Five things one team deliberately did not record, with the reason
What was said about a colleague's performance
Discussed and not minuted
A written version would have followed that person indefinitely
The reasoning behind a redundancy decision
Held by two people
Recorded only in the formal documents that had to exist
A client's private remark about their own board
Repeated verbally where needed
Writing it down would have put it somewhere it could be forwarded
Credentials, in any page
Kept in the credential store
Asked for four times and refused four times
An individual's reason for leaving
Known to their manager
Written nowhere, correctly
five things nobody wrote down · 12 occasions it cost somebody something
Five things, twelve occasions. Each of these would have been easier to handle if written down, and each was correctly left unwritten. A collection arguing for more writing has to be able to say where the answer is no. One team's own quarter.
Everything so far has argued for writing more. This page is the counterweight, and it is not a formality.
Some things are easier to work with when written down and should not be written down anyway. The reasons are about what a document does once it exists, which is travel, persist and be found by people it was not written for.
Anything about a person
Performance, difficulties, conduct, somebody's reason for leaving.
A written note about a colleague persists, is searchable, can be forwarded, and will be read by people who do not have the context in which it was written. It also outlives the situation: a sentence written in a difficult month follows somebody for years.
Where a record genuinely has to exist — formal processes do require them — it belongs in whatever system is meant for that, with whatever protections apply, and not in a team page.
This is one of the places where what an employer may or must record about an individual is governed by rules that differ by place and change, and the answer for any particular case comes from somebody qualified there rather than from a general principle.
Credentials and secrets
Obvious, and requested constantly, usually with a reasonable justification about convenience.
A credential in a page is a credential in every backup, every export, every search index and every person's local copy, for as long as those exist. The convenience is real and the exposure is permanent.
The correct response to "can you just put it in the runbook" is a link to where it actually lives.
Things said in confidence
A client's remark about their own organisation. A colleague's disclosure about their circumstances. Something told to you because you were the person in the room.
Writing these down converts a confidence into a record, and the person who gave it has no way of knowing that happened.
Speculation about people or organisations
Why somebody did something, what a client is probably thinking, what is going on at a partner organisation.
Spoken, this is a working hypothesis that evaporates. Written, it is a claim with a date and an author, discoverable later, and frequently wrong in a way that is embarrassing to everybody.
Three questions before publishing
Three questions, and a yes to any of them is a reason to stop.
Would this harm somebody if read by a person it was not written for?
Is it a claim about a person rather than about work?
Would the subject be surprised to find it written down?
None of these requires a policy. They require a few seconds before publishing, which is a habit rather than a process.
What to write instead
In most of these cases something can still be recorded, in a form that loses the harmful part.
Not what was said about a colleague, but that a conversation happened and when. Not the credential, but where it lives and who can grant it. Not the client's private remark, but the decision it led to.
That is usually enough for the operational purpose, which is what the page was wanted for in the first place.
The five categories
Short enough to hold in mind, which is what it needs to be, since the decision is made in the few seconds before publishing.
- Anything about a person — performance, conduct, reasons for leaving.
- Credentials and secrets, however convenient it would be.
- Things said in confidence, by a client or a colleague.
- Speculation about people or organisations.
- Anything the subject would be surprised to find written down.
The fifth overlaps the others and catches what they miss. It is also the only one that works without anybody having to classify the material first, which is why it is the one to remember.
Why this belongs in a collection arguing the other way
Because the main argument is easier to dismiss without it.
A team that has been told to write everything down will, at some point, write down something it should not have, and the resulting incident becomes the reason the whole effort stops.
Saying where the line is, early and specifically, is what makes the rest of the argument safe to act on.
Recording the operational part
In most of these cases something can still be written down, and the version that survives the test is usually enough for the purpose the page was wanted for.
| Do not write | Write instead |
|---|---|
| What was said about a colleague | That a conversation happened, and when |
| The credential | Where it lives and who can grant it |
| A client's private remark | The decision it led to |
| Why you think somebody did something | What they did, and what you asked them |
Each right-hand entry carries the operational content and none of the exposure, and each takes the same time to write as the thing it replaces.