Conventions
How every entry in this encyclopedia is structured and written. Following these makes the whole thing feel cohesive and predictable, so I (and any future contributor) can navigate confidently.
1. Voice and tone
- Plain English first. Imagine you’re explaining the concept to a smart friend who is not a programmer. They have curiosity and patience, but no jargon tolerance.
- Define every technical word the first time it appears in an entry, then link to its glossary entry on subsequent uses.
- Show, don’t just tell. Almost every entry should include at least one concrete example — even if it’s a tiny one-liner.
- Be honest about complexity. If something is genuinely confusing or subtle, say so. Don’t pretend it’s simple.
- No condescension, no false modesty. Treat me as capable of learning anything — just not all at once.
2. Entry structure
Every entry — whether glossary, textbook, or how-to — should have the same skeleton wherever it makes sense:
# {Title}
> **Status:** 🟥 STUB | 🟨 DRAFT | 🟩 COMPLETE | 🟦 LIVING
> **Last updated:** YYYY-MM-DD
> **Plain-English tagline:** {one sentence — what is this, really?}
## In plain English
{The "if you remember nothing else" explanation. 2-5 sentences. No jargon without explanation.}
## Why it matters
{What problem does this solve? What would the world look like without it?}
## How it works
{The conceptual model. Diagrams in ASCII or descriptions are fine. Skip if not relevant.}
## A concrete example
{The smallest meaningful example. Code is welcome but always annotated.}
## Common gotchas
{Bullet list of things that trip people up.}
## See also
{Cross-links to related entries.}
## Sources
{Links to authoritative external sources when applicable.}Not every section is required. A glossary one-liner just needs Title + tagline + In plain English + See also. A textbook chapter might have all sections plus extras (history, variants, advanced notes).
Recognized entry formats
Different content shapes call for different layouts. The encyclopedia uses these:
| Format | Lives in | Shape |
|---|---|---|
| Textbook entry | Section folders (01-foundations/, 02-frontend/, etc.) | The 7-section template above. The default. |
| Glossary entry | glossary/<letter>.md | Title + tagline + 1–4 sentence definition + See also. Many per file, one per term. |
| How-to guide | how-to/ | Numbered procedural steps; always testable. |
| Reading path | reading-paths/ | Curated trail of links with one-line “why this comes next” per stop. |
| Case-study reading path | reading-paths/ | Narrative walkthrough of a real project, with links to the entries that explain each piece. |
| Cheat sheet | cheat-sheets/ | Commands grouped by intent + workflows + gotchas + see-also. NOT 7-section. |
| Common-errors reference | common-errors/ | Error message fragment → meaning → fix lookup table. NOT 7-section. |
| Decision framework | decision-frameworks/ | ”When to use X vs Y” — short answer + factors + when-to-pick-X + when-to-pick-Y + migration paths. NOT 7-section. |
| Vendor entry | Section folders + ai-landscape/ | Country badge in title + front-matter facts block + 9-section body (see “Vendor entry format” below). Used for AI-provider / AI-product entries. |
| AI landscape reference | ai-landscape/ | Cross-cutting reference about the AI ecosystem (vendor lists, comparison matrices, geopolitical guides, capability rollups). |
Cheat sheets and common-errors references are intentionally shorter than textbook entries. They’re skim-readable; the textbook entries they link to provide depth.
When you add a new format that doesn’t fit any of these, document the shape here and update the relevant collection’s index.md to explain how it should be used.
Vendor entry format (used for AI providers and AI products)
Vendor entries describe a specific company or product (ChatGPT, Cursor, Adobe Firefly, etc.). They differ from textbook entries because the headline information a reader wants — what is it, where is it made, is it safe to use, what does it cost — needs to be one glance away. They also carry an explicit geopolitical marker because the encyclopedia recommends Western tools and recommends against Chinese-origin tools.
Title line. Always starts with a country-of-origin flag and the country name, then the product. For Chinese-origin tools, also append — ⛔ DO NOT USE.
Examples:
# 🇺🇸 USA · OpenAI ChatGPT# 🇫🇷 France · Mistral Le Chat# 🇦🇺 Australia · Atlassian Rovo# 🇨🇳 China · DeepSeek — ⛔ DO NOT USE
Recognised flags so far: 🇺🇸 USA, 🇬🇧 UK, 🇫🇷 France, 🇩🇪 Germany, 🇪🇺 EU, 🇨🇦 Canada, 🇦🇺 Australia, 🇳🇿 New Zealand, 🇮🇱 Israel, 🇨🇳 China. Add others as they come up.
Status line. Standard 🟩 COMPLETE (with 🟦 LIVING for anything that changes more than once a year — most vendor entries qualify).
Front-matter facts block (a single table, always in this order):
| Field | Value |
|---|---|
| Vendor | Company name + city/country |
| Country / origin | Flag + country |
| Recommended for Australian users? | ✅ Yes / ⚠️ Caution / ⛔ No (with one-line reason) |
| Privacy summary | One-line: does it train on your input by default? Can you opt out? |
| Free tier | Yes / No / Trial only — one-line of what’s included |
| Paid tiers | Plan names and AUD or USD prices (most accurate as of “Last reviewed”) |
| First released | Date |
| Last reviewed | YYYY-MM-DD — the date this entry was last fact-checked |
| Official site | URL — omit for ⛔ entries, write (not linking — pick a Western alternative) |
Western-alternatives row (added only to Chinese-origin entries, replaces the official-site row):
| Western alternatives by capability | Chat → Claude · Code → Claude Code · Image → Imagen · Video → Veo · (etc., as relevant) |
Body sections (in order; skip a section only if it genuinely has nothing to say):
- What it is — one-paragraph plain-English description plus an analogy if useful.
- What you’d use it for — concrete jobs it’s good at. Bullet list.
- How to sign up + first 5 minutes from Australia — for Western entries, a numbered step-by-step. For ⛔ entries, replace with “Why we recommend against it” + “What to use instead”.
- What it costs — what you actually get — free-tier line items, then per-tier breakdown. Honest about hidden costs (token overages, paid add-ons, GST handling for AUS billing).
- How it compares to alternatives — comparison table. Always include the nearest 2-3 Western alternatives.
- Privacy / data handling deep dive — does it train on your input? How long is data stored? Who can access it? Opt-out steps with screenshots-described-in-words.
- Gotchas — topic-specific traps.
- Recent changes (LIVING entries only) — short list of meaningful version bumps since the entry was last reviewed.
- See also — 3-8 related entries with status badges + glossary links.
- Sources — official docs first, then trustworthy third-party.
When to use the vendor format. Any entry that profiles a specific company or product — frontier AI assistants, coding agents, design tools, cloud providers, etc. Capability-concept entries (image generation as a concept) keep the textbook format. Cross-cutting landscape references (capability matrices, decision frameworks, geopolitical guides) keep their existing formats from this conventions file.
3. Status labels
Status sits at the top of every entry as a blockquote. Four possible values:
| Badge | Meaning |
|---|---|
| 🟥 STUB | Title and tagline only. No real content yet. Listed so we know it’s a planned topic. |
| 🟨 DRAFT | Substantive content, but rough or incomplete. Use cautiously; verify before relying on it. |
| 🟩 COMPLETE | Written, reviewed, cross-linked, sourced. This is the gold standard. |
| 🟦 LIVING | Written and reliable, but the underlying topic itself evolves frequently (e.g. specific tool versions, AI model lineups). Treat as a snapshot. |
When upgrading status, update the Last updated date too.
4. Cross-linking
Cross-links are how the encyclopedia comes alive. Be generous with them.
Within the encyclopedia — use relative markdown links:
See also [Row-Level Security](../04-databases/row-level-security.md) and [Supabase](../04-databases/supabase.md).To the glossary — link to the specific letter file:
A [JWT](../glossary/j.md#jwt) is...To external sources — full URL, link text describes the destination:
[Next.js App Router docs](https://nextjs.org/docs/app)When to link:
- First mention of a defined term in any entry → link to its primary entry
- Anywhere a reader might ask “but what does X mean?” → link to X
- At the bottom of every entry, a “See also” section listing 3–8 related entries
Status badges on cross-links — the bump protocol
Every link in a “See also” section gets a status badge after the link text:
- [Vercel](../06-hosting-and-deployment/vercel.md) 🟩 🟦 — the deploy platform
- [Some stub](../somewhere/not-yet.md) 🟥The badge tells the reader what to expect before clicking. The encyclopedia stays honest about its own state.
The bump protocol: when an entry’s status changes (most commonly 🟥 → 🟩), every OTHER entry that links to it should update its badge. There’s no automatic propagation — only discipline.
The rule:
- When you upgrade a stub to complete, immediately grep for the filename across the encyclopedia (e.g.
Grep "tool-use.md"finds every See-also that points at10-ai-and-llms/tool-use.md). - Update each See-also that referenced the old status — flip
🟥to🟩(or🟩 🟦if the entry is also LIVING). - Do it in the same session as the upgrade. If you defer, the bump gets forgotten and the rot compounds invisibly.
Why this matters (the 2-axis rot model): sessions 36–42 of the build (June 2026) corrected 108 stale badges across 27 anchor entries in a multi-session sweep. The pattern that emerged: badge rot scales with how OLD an entry is AND how many sections its See-also points into. Intra-section anchors stay clean naturally (their cross-links closed within the same writing window). Cross-section anchors written early rot fastest as downstream sections complete later.
The audit-and-fix sweep is the recovery move. The bump protocol is the prevention. Doing the bump at upgrade time costs 60 seconds; missing it costs an entire sweep session later.
5. File naming
- Use kebab-case (lowercase, words separated by hyphens):
row-level-security.md, notRowLevelSecurity.mdorrow_level_security.md. - Use the same name as the entry title, simplified. “Row-Level Security (RLS)” →
row-level-security.md. - Glossary files are named by letter:
a.md,b.md, …,z.md. Each contains all glossary entries starting with that letter. - Section index files are always
index.md(lives in the section folder root).
6. Code examples
- Always use fenced code blocks with a language hint:
```ts const greeting = "hello"; ``` - Annotate non-obvious lines with inline comments.
- Keep examples as small as humanly possible while still being useful. Trim everything not needed to make the point.
- Examples can be as long as the topic genuinely needs. If an example is very long (no hard limit), consider whether linking out to a separate
examples/file in the section folder would aid readability — but never trim a meaningful example just to hit a length target. Quality and clarity over arbitrary line counts.
7. Updating entries
When changing an existing entry:
- Update the Last updated date.
- If the change is significant (new section, corrected mistake, status upgrade), add a one-line note to CHANGELOG.md.
- If a fact changed because the underlying tech moved (e.g. Next.js version bump), consider flipping status to 🟦 LIVING.
- Never silently delete content — if something is wrong, replace it and note the correction in the changelog.
- When promoting status (🟥 → 🟩 or any upgrade), run the back-link bump protocol — see section 4. Grep for the entry’s filename, update every See-also that references the old badge. Do it the same session.
8. Linking to external sources
When citing an external source:
- Prefer official docs over blog posts. (MDN > Stack Overflow > random Medium article.)
- Include the source’s name in the link text:
[MDN —fetch()](https://developer.mozilla.org/...). - Note the date you accessed it if the source is likely to drift.
- For LLM behavior, link to the relevant Anthropic/OpenAI docs rather than third-party explainers.
9. Emojis and icons
- Status badges always use the colored square emoji (🟥🟨🟩🟦) so they pop visually.
- Otherwise, emojis are optional and sparing. They’re fine for the README and section indexes where they help navigation. They are not required in regular entries.
10. Length discipline
- Glossary entries: 1–4 sentences usually. A paragraph at most. If it needs more, write a textbook entry and link to it from the glossary.
- Textbook entries: as long as the topic deserves, but always with sub-headings so the reader can scan. A complete one might be 800–2,000 words.
- How-to guides: as long as the procedure requires. Always numbered steps. Always testable.
- Reading paths: a curated list of links with one-line “why” per stop. Typically 500–1500 words.
- Case-study reading paths: narrative-with-embedded-links covering a real project end-to-end. Longer than goal-oriented paths; typically 2500–4000 words.
- Cheat sheets: quick reference cards — commands grouped by intent + workflows + gotchas. Typically 600–1200 words.
- Common-errors references: lookup tables organized by error message. Length scales with how many distinct errors are covered (usually 10–30 errors per reference).
Length depends on context — there is no hard limit. Long entries can be the right call if the topic genuinely needs the depth and the structure is scannable (clear sub-headings, tables of contents for very long ones). Short entries can be the right call too. Splitting is a tool to consider, not a rule to follow blindly. Quality and clarity of the specific topic decide the length.