DEV Community

Daniel Pertu
Daniel Pertu

Posted on

A document we deleted in September is cited 73 times in our code, and the file explaining the citation convention is one of the citers

I was grepping this repo for something unrelated when I noticed a comment pointing at a file I could not remember seeing:

/**
 * Required legal/regulatory strings (PLAN.md §4, §13; SCREENS.md §0).
 */
Enter fullscreen mode Exit fullscreen mode

SCREENS.md is in docs/. PLAN.md is not. So I counted.

73 citations of PLAN.md, across 43 files
Enter fullscreen mode Exit fullscreen mode

Broken down by where they live:

packages/rules-engine    56
apps/mobile              11
apps/web                  4
packages/content          2
Enter fullscreen mode Exit fullscreen mode

Twelve distinct section numbers are cited, including two sub-sections, §4.5 and §4.6. One section, §6, is cited 32 times on its own. And the document has not existed since the 2nd of September, when it was deleted as part of a commit called "Migrate backend to Next.js, implement OCR and menu mode", a commit that changed 161 files, added 11,682 lines and removed 3,920. The deletion is not mentioned in the message, and I cannot tell from the diff whether it was deliberate; what is certain is that nothing else in the commit updated a single citation of it.

The convention was real, and it was good

This is not a story about sloppy comments. The citations are precise, they are consistent, and they were load-bearing. Here is one from a rate limiter:

// `analytics: false` keeps zero events off any third party (PLAN §13).
Enter fullscreen mode Exit fullscreen mode

That line explains a one-word config option by pointing at the section of the plan that makes it necessary. Without the citation it reads as a performance tweak that somebody could reasonably turn back on. With it, it is a privacy commitment with a document behind it. The citation is doing the work that a comment saying "don't change this" cannot do, because it says why rather than just no.

And the practice was formalised. docs/ARCHITECTURE.md opens with its own status note, and its third sentence is this:

Cross-references are to PLAN.md sections (§).

So the surviving document that explains the citation convention is itself a citer of the missing document. SCREENS.md goes further and opens with a list of the plan sections it implements, four of them, before it describes a single screen.

Two documents and 43 source files are all pointing at the same hole.

Which sections, and why §6 is cited 32 times

The distribution is the tell. §6 is the engine section: the part of the plan describing how the app behaves per condition, which is the part of the product everything else exists to serve. 32 of the 73 citations point at it, and nearly all of them are inside one package, where the densest file carries 19 citations on its own.

The others cluster the same way. §4 is the regulatory positioning, cited from the places that print a legally required sentence. §13 is the privacy architecture, cited from the places that decide what leaves a device, which is why that rate limiter comment exists. §5 is the data strategy. Each citation sits exactly where a reader would want it.

Which is the problem. A citation is only as good as the thing it points at, and these ones now point at nothing, in the one package where somebody arriving fresh most needs the reasoning to be findable. The comment tells them a justification exists, tells them where it is, and the where is wrong. That is strictly worse than no comment, because a reader who finds no comment goes and asks. A reader who finds a dead reference concludes the documentation is stale and stops trusting the rest of it, including the parts that are fine.

The resolution is boring and that is the point

The document is not gone. It is in the history, one command away:

$ git show 106b23f^:PLAN.md | wc -l
218
Enter fullscreen mode Exit fullscreen mode

218 lines, 16 sections, exactly the sections the comments name. Nothing was lost except the ability to find it by the name the code uses.

So there were three options, and the ranking surprised me.

Restore it. Tempting, and wrong. It was deleted during a migration that moved the backend from one platform to another, and a plan written before that migration describes a stack that is no longer the stack. Restoring it puts a document back in docs/ whose §12 is confidently incorrect, and then 73 citations point at something worse than nothing: a wrong answer with a section number.

Rewrite the citations to point at the documents that do exist. Also wrong, at least as a first move, because the mapping is not one to one. The plan's §6 is not any single surviving document, and the honest replacement for some of those 32 citations is a paragraph that nobody has written yet.

Restore it under a name that says what it is. docs/PLAN-2026-08.md, a historical document, dated, with a line at the top saying it predates the migration and is kept because 73 comments cite it. Then the citations resolve, a reader gets the reasoning that was true when the code was written, and nothing claims to describe today's stack. The comments do not even need editing, though they should eventually say PLAN-2026-08.md §6.

That third one is the one I would have ranked last in the abstract, because keeping a stale document feels like the opposite of good hygiene. It wins because of what the citations are for. They are not navigation. They are provenance: this line exists because of that decision. Provenance does not stop being true when the decision gets superseded, and the right fix for a stale justification is a dated one, not a deleted one.

The four documents nothing cites

Here is the other half of the audit, which I did not expect to be the useful half. Ten documents live in docs/. Counting references from source files only:

TAXONOMY.md                 36 files
ARCHITECTURE.md             30
REWARDS.md                  23
PRODUCT-DATABASE-PLAN.md    20
SCREENS.md                   3
ADMIN.md                     1
BACKEND.md                   0
DATA-SCHEMA-SPEC.md          0
DB-BACKUPS.md                0
DESIGN-SYSTEM.md             0
Enter fullscreen mode Exit fullscreen mode

The top four are heavily cited and, not coincidentally, the four that are accurate. They get cited because they are useful, and they stay accurate because being cited means someone opens them, and opening a wrong document is how it gets fixed. REWARDS.md says of itself that it is the single source of truth for a mechanism and that the numbers live in one named module as constants, and 23 files take it at its word.

The bottom four are not necessarily bad documents. DB-BACKUPS.md describes an operational procedure that no source file has any business referring to, and a zero there is correct. But DESIGN-SYSTEM.md at zero, in a repo with three surfaces that have to look like the same product, is a document nothing can detect the staleness of. There is no reader whose expectations it is failing, which sounds comfortable and means it is drifting unobserved.

So the real finding is not the 73 dead citations. It is that citation count is a usable health metric for documentation, and it points both ways. A document with many citations and a missing file is an urgent, visible problem that announces itself to every reader. A document with zero citations and perfect spelling is a quiet one that will be wrong for a year before anybody notices, and the fix is not to write more documentation. It is to cite the documentation you have from the code it explains, so that deleting it hurts.

If you want the user-facing end of the sections above, the privacy notice is §13 as shipped, and the condition guides are what §6 produces. Both of those read fine without any of this, which is the whole point of writing the reasoning down somewhere else.

Top comments (2)

Collapse
 
docsalive profile image
DocsAlive Team •

Counting the citations was a clever way to surface this. A cheap guard against it happening again is a small CI script that scans source for references like PLAN.md section numbers and fails if the file or heading no longer exists. A few lines of grep plus a check that each cited section is present would have flagged that September commit immediately. Another option is a deletion rule: when a doc is removed, the same PR must either update every reference or leave a stub that points to the replacement. Either way the convention you describe stays useful instead of turning into dead pointers.

Collapse
 
mayur_gadakh profile image
Mayur Gadakh •

restoring it under a dated name like PLAN-2026-08 sounds right, at least the 73 citations resolve agian and the date tells people its history. one thing id ask is whether the section numbers are stable, because 32 citations pointing at one section means any reshuffle breaks them all over again. maybe short stable ids per rule instead of numbers. im building docup, it keeps docs generated from the repo so references like these have a living page to point at