# Glossary — [YOUR NEWSLETTER NAME]

How to handle technical terms, jargon, and acronyms in your newsletter.

**CUSTOMIZE Buckets 1-3.** Bucket 4 (banned acronyms) is universal — keep it as-is.

---

## Decision tree

When a sentence reaches for a technical term, framework, or tool name:

1. Is it universally understood by your floor reader? → Use it freely (Bucket 1)
2. Is it understood by your middle reader? → Use it with a brief inline gloss (Bucket 2)
3. Is it only understood by your ceiling reader? → Use a universal substitute or rephrase (Bucket 3)
4. Is it a banned acronym? → Never use it (Bucket 4)

---

## Bucket 1 — Always safe to use freely

[Terms your floor reader knows without explanation.
Example for a developer newsletter: function, class, variable, file, terminal, install, run]

- (add your list here)

---

## Bucket 2 — Use with a brief inline gloss (first occurrence only)

[Terms your middle reader probably knows, but your floor reader may not.
Format: "the term (brief 6-12 word explanation in parentheses)"]

- [e.g. "webhook (an HTTP callback that fires when an event happens)"]
- [e.g. "idempotent (safe to call multiple times with the same result)"]

---

## Bucket 3 — Replace with a universal example, or rephrase plainly

[Terms that only the ceiling reader knows. Don't use the term; describe what it does.]

- [e.g. "pnpm" → say "a package manager for JavaScript" or use a universal example]
- [e.g. "ruff" → say "a Python linter"]

---

## Bucket 4 — Banned acronyms (never use, universal rule)

These acronyms are banned in all newsletter content regardless of audience tier.
The floor reader doesn't know them. The ceiling reader doesn't need them.

| Acronym | Instead |
|---|---|
| TL;DR | "The short version" or "In short" |
| FWIW | "For what it's worth" or restructure |
| IIRC | "If I remember correctly" or drop the hedge |
| IMO / IMHO | State the opinion directly without hedging |
| AFAIK | "As far as I know" or drop |
| YMMV | "Results vary" or restructure |
| LGTM | Write it out ("looks good to me") or cut |
| ICYMI | "If you missed it" or restructure |
| CRUD | "create, read, update, delete" |
| REST / RPC | Define on first use or use plain description |
| DRY / KISS / YAGNI | Define on first use if used at all |

---

## Changelog

[Date + what changed + why]