Annotated

Podcast 2 — In conversation

Speaker A: I keep seeing annotated bibliography as a requirement on academic assignments. What exactly does it mean in practice, and why is it more useful than a regular bibliography?

Speaker B: A regular bibliography is simply a list of sources — author, title, date, publication. An annotated bibliography adds a brief paragraph after each entry — typically three to eight sentences — that does one or more of three things: it summarises the source's main argument, it evaluates the source's reliability or usefulness to the research, and it explains how the source relates to the project. The annotation transforms a list of citations into a curated reading guide. A reader looking at your annotated bibliography can immediately understand what each source contains and why you chose it, without reading the sources themselves. It is a significantly more intellectually demanding product than a plain list.

Speaker A: And what is the difference between annotated and commented in everyday use? I feel like I sometimes see them used for similar things, particularly in code.

Speaker B: In code, commented is the more common term — a commented line or commented-out block. Annotated in programming often refers specifically to metadata annotations — the kind you see in Java with the at-symbol before a keyword, like at-Override or at-Component — which are machine-readable tags that frameworks and compilers interpret, not just notes for human readers. So commented code is for humans; annotated code is often for machines as well. Outside programming, annotated is the broader, more formal word. You annotate a text, a map, a legal document. Comment is more colloquial: I added a few comments in the margin is more casual than I annotated the margins, which implies something more systematic and scholarly.

Speaker A: And glossed — I see that used occasionally. Is that a near-synonym for annotated?

Speaker B: Glossed is indeed close but more specific. A gloss is an explanatory note attached to a difficult or obscure word — it explains the word itself rather than its wider context. A glossed manuscript has individual words translated or explained; an annotated manuscript has notes that may discuss historical context, textual variants, thematic connections, and anything else the annotator finds relevant. Glossed is narrower — word-level explanation. Annotated is broader — any form of supplementary notation, from a word-level gloss to a full critical apparatus.

Podcast 3 — Prompt engineering

Speaker B: Annotated is one of the most precise and powerful words in the developer's prompting vocabulary. When you use it in a prompt, you are asking the AI to produce output that carries explanatory metadata alongside the primary content — whether that is code with inline comments, datasets with labels, API responses with descriptions, or documentation with worked examples. It transforms a simple generation request into a request for something that teaches as it delivers. Let me show you how it works across real scenarios.

Speaker A: The distinction between code that works and annotated code that teaches — that feels like the core value. Can you start with a code generation example?

Speaker B: Exactly that. First — annotated code generation:

Speaker B: PROMPT:

Speaker A: Annotated code for a junior developer audience — the audience specification interacts with the annotated requirement to produce a very specific output: deep comments that explain the why as well as the what. Without annotated, you would get working code with minimal comments.

Speaker B: Now an annotated database schema:

Speaker B: PROMPT:

Speaker A: SQL comments on every schema element — that is an annotated schema in the strict sense. The annotations on indexes and nullable columns are the ones that save the next developer hours of reverse-engineering what the original designer intended.

Speaker B: Now an annotated API design:

Speaker B: PROMPT:

Speaker A: An annotated OpenAPI spec as self-sufficient documentation — that is the right way to think about it. If every field and endpoint has a description that explains the business logic, developers can integrate without needing a separate wiki page.

Speaker B: Now a machine learning data prompt:

Speaker B: PROMPT:

Speaker A: The annotation note for ambiguous cases — that is the human-in-the-loop quality signal that makes training data actually useful. Raw labels without annotations on edge cases produce models that fail on exactly the cases that matter most.

Speaker B: Now a full application prompt:

Speaker B: PROMPT:

Speaker A: A side-by-side view of original versus annotated code — that is a genuinely useful teaching and review interface. The platform is essentially building a structured code review tool where the annotation is the product, not just a sidebar feature.

Speaker B: Use annotated in prompts whenever you need the AI to produce output that explains itself — code that teaches, schemas that document their own design decisions, datasets that carry their labelling rationale, APIs that describe their own business logic. The word signals to the AI that the primary output is not enough; the understanding of that output must be built into the delivery.