How glossary/terms.md Works in the AI Engineering From Scratch Curriculum

The glossary/terms.md file serves as the single source of truth for domain-specific terminology in the rohitg00/ai-engineering-from-scratch repository, requiring new entries only for cross-cutting concepts while following a strict three-bullet format.

The glossary/terms.md file in the AI Engineering From Scratch curriculum functions as a living textbook that standardizes vocabulary across all lessons. Maintaining this centralized glossary ensures learners encounter consistent definitions whether they are exploring LoRA in lesson three or KV Cache in lesson twelve.

Structure and Format of glossary/terms.md

The glossary is a plain Markdown document organized alphabetically. The rigid structure enables automated tooling and predictable navigation for learners.

Alphabetical Organization

The file uses second-level headings for letters (## A, ## B, etc.) and third-level headings for individual terms.

## L

### LoRA (Low‑Rank Adaptation)

Each term must reside under its alphabetical heading. If a section is missing, contributors create it following the existing pattern.

The Three-Bullet Entry Pattern

Every term entry follows a uniform three-bullet structure:

1. What people say – The colloquial or intuitive description
2. What it actually means – The precise technical definition used throughout the curriculum
3. Why it’s called that – Historical or etymological context (optional but recommended)

### LoRA (Low‑Rank Adaptation)

- **What people say:** "Efficient fine‑tuning"
- **What it actually means:** Instead of updating all weights, small low‑rank matrices are inserted alongside the original weights. Only these adapters learn, cutting memory usage 10–100×.
- **Why it's called that:** "Low‑Rank Adaptation" describes the mathematical property (rank‑reduced updates) that makes the technique cheap.

When to Add New Terms to glossary/terms.md

Not every technical term deserves a global entry. The repository follows strict inclusion criteria to prevent glossary bloat.

Three Conditions for Inclusion

A term should be added iff it meets one of these conditions:

• It appears across multiple lessons – Terms referenced in several phases of the curriculum (e.g., "Agent", "Attention") require centralized definitions to maintain consistency.
• It is a core concept – Foundational ideas learners encounter repeatedly, such as "LoRA" or "KV Cache", belong in the glossary even if initially introduced in a single lesson.
• It is a newly introduced concept with future references – If a term will be referenced in upcoming lessons, add it immediately upon introduction, even if currently used only once.

When to Keep Definitions Local

If a word represents one-off jargon used only inside a single lesson's narrative, define it within that lesson's docs/en.md file instead of polluting the global glossary. This prevents glossary/terms.md from becoming cluttered with ephemeral terminology.

How to Add a New Term

Contributing to the glossary requires adherence to both formatting and repository workflow conventions.

Step-by-Step Contribution Process

1. Locate the alphabetical section – Find the appropriate ## X heading or create a new one if missing

2. Insert the term heading – Use a third-level heading with the capitalized term name: ### Term Name

3. Populate the three bullet points – Mirror the style of surrounding entries exactly

4. Commit following conventions – Use the format feat(glossary): add TermName

Repository Workflow Constraints

According to AGENTS.md, the curriculum enforces a "one commit per lesson" rule. If the glossary update coincides with a new lesson, include it in that lesson's commit. If updating the glossary independently, isolate it to its own pull request dedicated to this single change.

# Example commit for standalone glossary update

git commit -m "feat(glossary): add KV Cache"

Build System Integration

The curriculum's build script (site/build.js) does not transform the glossary content; it ships the raw Markdown directly to the website. The only technical requirement is that glossary/terms.md remains valid Markdown with correctly nested headings. The build will fail if headings are improperly structured or if the file is missing from its expected path.

Lessons reference glossary entries using standard Markdown links:

<!-- Example from a lesson's docs/en.md -->

### Attention

> **See also:** [Attention](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md#attention)

Summary

• The glossary/terms.md file acts as the centralized terminology dictionary for the AI Engineering From Scratch curriculum, located at the repository root
• Entries follow a strict alphabetical structure with a three-bullet pattern (common speech, technical reality, naming rationale)
• Add terms only when they cross multiple lessons, represent core concepts, or will be referenced in future content; keep one-off jargon in local lesson files
• Commit changes using conventional commit format (feat(glossary): add Term) and respect the one-commit-per-lesson rule defined in AGENTS.md
• The build system (site/build.js) serves the file raw, requiring only valid Markdown syntax

Frequently Asked Questions

How do I format a new term in glossary/terms.md?

Locate the alphabetical section (e.g., ## K for "KV Cache") and add a third-level heading with the term name. Below the heading, include three bullet points: what people commonly say, what it technically means in the curriculum, and optionally why it has that name. Follow the exact indentation and bolding pattern of existing entries.

Can I edit an existing term's definition?

Yes, but treat definition updates as content corrections. If the change fixes an error, use fix(glossary): correct TermName definition. If it expands the definition for clarity without changing meaning, use docs(glossary): clarify TermName. Remember that AGENTS.md requires one commit per logical change, so don't bundle unrelated glossary edits.

Why was my glossary contribution rejected?

Common rejection reasons include: adding terminology used in only one lesson (belongs in that lesson's docs/en.md instead), deviating from the three-bullet format, or bundling the glossary update with unrelated lesson changes. The repository enforces atomic commits; glossary additions must stand alone unless part of a lesson's initial PR.

Does the build process modify glossary/terms.md?

No. The site/build.js script treats glossary/terms.md as a static asset. It validates that the file exists and contains valid Markdown, then serves it directly without transformation. This raw approach ensures that links from lesson files always resolve correctly and that the document remains readable in both GitHub's interface and the built website.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}