A Good Name Is a Doc You Never Write
Names like is_active and MAX_RETRY explain themselves. How small symbols and shared title shapes work as docs, and what a wiki with 20 title prefixes costs.
When a senior engineer sees is_active, they know that it is a bool. When they see MAX_RETRY, they know that it is a constant. Nobody writes this down, and nobody needs to.
That is the Bullet Journal idea: small symbols, big meaning.
Small symbols
| Symbol | Meaning |
|---|---|
| • | a task |
| ○ | an event |
| - | a note |
| ★ | an extra mark: important |
| index + page numbers | where to find it, and in which order |
Even the type of list carries meaning. A numbered list means “do it in this order”. A bullet list means “any order is fine”.
We already do this
- Pull request:
[TICKET-123][TICKET-124] ci: align some-service ... - Branch:
<name>/TICKET-123/delete-old-harness - ADR:
0001-.... The number gives both the order and the address.
We just never called it a rule.
A counterexample: a wiki with no shared shape
Picture a typical product space in a team wiki (Notion, Confluence), the kind that many companies have. This one has 23 product folders.
- About 20 title prefixes:
[Design Doc],[FE Design Doc],[BE Design],[Note],[User Flow], and more. - Status in the title, written five ways:
(TBD),(Undone),[Dep],[?],(Deprecated). - Meeting notes in five shapes, and release notes in four.
- One shared widget that appears in three product folders.
Which page is the current one? A new team member cannot tell. If nobody can find a doc, it is the same as not writing it.
There is a good example too. The <Name>'s Handover pages are 9 pages with one shape. You know what each one holds from the title.
When names do not match, search and tags split the same way. See Remember Where, Not What. How much a name must say depends on the reader. See Write Only What Your Reader Cannot Find.
A good name is a doc that you never have to write.
References
Related: see why tags split like names do, revisit Strict Rules Only Where a Machine Checks, or go back to the series overview: Docs in the AI Era.