Craft without documentation dies in Slack threads. This capstone of Module 13.2 shows how teams record purpose, owners, versions, evals, and known failures so prompts survive handoffs. Next, Module 13.3 starts with token counting—measuring the cost of what you wrote.
Learning Objectives
By the end of this lesson, students should be able to:
- Write a prompt doc with purpose, owner, inputs, outputs, and risks.
- Link documentation to template IDs and eval suites.
- Record change history with hypotheses and metric deltas.
- Publish known failure modes and escalation paths.
- Make docs usable for engineers, PMs, and support leads.
- Connect documentation discipline to Module 13.3 cost controls.
Prompt documentation is the living record that explains what a production prompt is for, how it is rendered, how quality is measured, who owns it, and how to change it safely.
Minimum Doc Outline
| Section | Contents |
|---|---|
| Identity | Name, template_id, version, owner, status |
| Purpose | User problem, success definition |
| Interfaces | Slots/inputs, output schema, models/tiers |
| Behavior | Persona, tone, negatives, safety |
| Quality | Golden set link, metrics, last scores |
| Operations | Rollback, on-call, known issues |
Before / After
Before (weak):
After (strong): excerpt of a real doc stub.
Who Reads Prompt Docs?
Engineers
- Slots & schemas
- Validation hooks
- Version diffs
PMs / Design
- Purpose & tone
- Acceptance metrics
- User-visible copy rules
Support / Risk
- Known failures
- Escalation paths
- Safety boundaries
“The prompt text is the documentation.” The prompt is the implementation. Docs add ownership, intent, eval evidence, and operational playbooks that the raw string cannot carry alone.
Knowledge Check
- Short Answer: What is prompt documentation? Answer: The living record of purpose, interfaces, quality, ownership, and safe change.
- True/False: The raw prompt string alone is sufficient documentation. Answer: False.
- Multiple Choice: template_id + version mainly support: (a) ownership/rollback, (b) convolution, (c) dropout. Answer: (a).
- Short Answer: Name two audiences for prompt docs. Answer: Any two of engineers, PMs/design, support/risk.
- True/False: Docs should link to golden-set scores. Answer: True.
- Multiple Choice: Known issues belong in: (a) operations section, (b) tokenizer vocab, (c) GPU firmware. Answer: (a).
- Short Answer: What should a changelog entry include? Answer: Hypothesis, change, metric delta, decision.
- Short Answer: Why document escalation paths? Answer: So on-call/support know when to hand off or roll back.
- Multiple Choice: Module 13.3 next focuses first on: (a) token counting, (b) CNNs, (c) k-means. Answer: (a).
- True/False: Documentation discipline helps control cost and quality over time. Answer: True.
Key Takeaways
- Document identity, purpose, interfaces, quality, and operations.
- Link docs to template versions and eval evidence.
- Write for every stakeholder who touches the feature.
- Treat docs as part of the release, not an afterthought.
- Next module: Token Counting.
Hands-on idea: Have teams fill the minimum outline for one feature prompt and peer-review gaps.
Discussion prompt: Where should prompt docs live—repo README, wiki, or config catalog UI?
Recap: Documentation makes prompt craft durable for teams. Continue to Token Counting in Module 13.3.