lerp

LERP: Least Experienced Reader Principle

Write for the person who just joined the team, opened this file cold, and has never seen the codebase before. If they cannot understand what you wrote without asking someone, the prose has failed.

This is not about dumbing things down. It is about making sure every sentence carries the context it needs to stand on its own.

The test

Read every sentence. For each one, ask: "If I had never worked on this project, would I know what this means?" If the answer is no, rewrite it until the answer is yes.

Rules

1. Spell it out, then abbreviate

Every acronym and abbreviation gets spelled out on first use, with the short form in parentheses. After that, the short form is fine.

Bad:  "VFS dispatches FUSE ops to the metadata store."

Good: "The Virtual Filesystem Switch (VFS) receives FUSE (Filesystem
      in Userspace) requests from the guest kernel. The VFS turns
      them into SQLite queries."

Domain terms that are not acronyms still need a plain-English explanation on first use. Not in a glossary at the bottom. Inline, right where the term appears.

Bad:  "The inode table maps paths to attributes."

Good: "The inode table (the index that maps every file path to its
      metadata like permissions, size, and timestamps) is stored in
      SQLite."

After the first occurrence, use the term or acronym freely. The reader has been introduced.

2. No orphan references

When you say "this split" or "this pattern" or "this approach," the reader must be able to point to exactly what you mean without reading a different file. If the antecedent is not in the same paragraph, restate it.

Bad:  "This split is what makes hard links work."

Good: "Separating names from attributes into two tables is what makes
      hard links work. Without it, two names pointing to the same
      file would each carry their own copy of the attributes, and
      those copies could drift out of sync."

The bad version says a thing is important but never says what breaks without it. The good version explains the consequence.