Documenting It So It Survives

An undocumented automation is a liability with a countdown on it. It breaks while you are on holiday, or you return to it in March and cannot remember what it does or how to stop it.

This is also the step that separates "I built a thing" from "I built a thing my team uses" — which is the difference that matters professionally.

---

1. The one-page SOP

One per workflow. If it does not fit on a page, the workflow is too complicated and should be split.

# SOP: [NAME]

Owner: [WHO]            Backup: [WHO]
Created: [DATE]         Last reviewed: [DATE]

## WHAT IT DOES
[Two sentences. What problem, what outcome.]

## WHEN IT RUNS
Trigger: [PRECISELY]
Filter:  [WHAT IS EXCLUDED]
Volume:  [N] per [PERIOD]

## THE STEPS
1. [STEP] -> [WHAT COMES OUT]
2. [STEP] -> [WHAT COMES OUT]
3. [STEP] -> [WHAT COMES OUT]

## WHERE THINGS LIVE
Workflow:     [LINK]
Prompts:      [LINK]
Knowledge:    [LINK]
Logs:         [LINK]
Credentials:  [WHERE, AND WHO CAN ROTATE THEM]

## THE HUMAN STEP
Who reviews:      [WHO]
What they check:  [SPECIFICALLY WHAT]
If they do not:   [CONSEQUENCE]

## WHEN IT BREAKS
| Symptom | Likely cause | Fix |
|---|---|---|
|  |  |  |

TO STOP IT: [EXACT STEPS]
Manual fallback while it is down: [WHAT TO DO INSTEAD]
If you cannot fix it: [WHO TO CONTACT]

## COST
Per run: [X]    Per month: [Y]    Alert set at: [Z]

The three lines people omit and later need: how to stop it, the manual fallback, and who can rotate the credentials.

---

2. Writing it with AI

Here is my workflow, step by step: [DESCRIBE IT]
Here are the prompts it uses: [PASTE]

Write a one-page SOP using the template below.
Then list what you could NOT determine from what I gave you.

[PASTE TEMPLATE]

That second instruction is the useful half. The gaps it finds are exactly the questions a new person would ask on day one.

---

3. Keeping prompts outside the workflow

A prompt buried inside an automation step has all the properties of untracked code: no history, no review, no rollback.

Keep them in one document, with a header:

PROMPT: support-ticket-classifier
VERSION: 4
UPDATED: [DATE]
USED BY: [WHICH WORKFLOW, WHICH STEP]
MODEL: [MODEL AND TEMPERATURE]

CHANGELOG
v4  Added "other" category — v3 forced everything into four buckets
v3  Constrained output to a single word, no punctuation
v2  Lowered temperature to 0.1 — routing was non-deterministic
v1  Initial

The changelog is the valuable part. Six months later, "why is there an 'other' category?" has an answer, and you do not undo a fix you have forgotten the reason for.

---

4. A test set per prompt

Ten to twenty real inputs with their correct outputs. Run them before and after any change.

#	Input	Expected	v3	v4
1			✓	✓
2			✗	✓

Twenty minutes to build. It converts "I think this is better" into "this fixed 3 and broke none", which is the difference between editing and engineering.

It also catches the silent failure: providers update models under the same name. Re-run your test set monthly. When output quality drops with no change on your side, check the model version before rewriting anything.

---

5. The evidence pack

For the capstone submission, and for your own record later:

• Baseline, measured before you built anything
• Result, measured the same way after
• A short recording or screenshots of it running on real input
• One real example of input and output, redacted if needed
• The prompts, so someone can see the constraints you wrote

---

6. The write-up

PROBLEM
[Who had it, how often, what it cost]

BASELINE
[The measurement, before]

APPROACH
[What you built, plain English, two paragraphs]

RESULT
[The measurement, after — including what did not improve]

WHAT WENT WRONG
[The failures and what you learned]

WHAT I WOULD DO DIFFERENTLY
[One or two things]

The "what went wrong" section is the one that gets you hired. Anyone can describe a working system. Describing how you diagnosed and fixed it demonstrates you actually built it rather than followed a tutorial.

Every real build breaks. A write-up with no failures in it reads as one that was never run.

---

7. The demo

Two minutes. Three parts.

1. The before. "This took 40 minutes every Monday. Here is what I actually did."
2. The after. Run it live, or show a recording. Real input, real output.
3. The number. "40 minutes to 6. Here is how I measured it."

Do not explain the architecture unless asked. Nobody cares which platform you used. They care that the problem went away.

---

8. Review cadence

Date	Still in use?	Still working?	Cost	Changes

Quarterly. If it has not been used in three months, turn it off — an unused automation still costs money and still breaks.

---

⚠️ Common Mistakes

• Documenting at the end. Write it as you build; you will not remember the decisions later.
• No "how to stop it". The line you need most, in the moment you need it most.
• Prompts only inside the workflow. No history, no rollback, no review.
• No test set. Every prompt change becomes a guess.
• A write-up with no failures. Reads as untested, and wastes the most valuable part of what you learned.
• Documenting for yourself. Write it for someone who has never seen it, because that is who will read it.

---

What's Next: The build is done and documented. The last lesson is about what happens after the course ends — which is where most of the value either compounds or evaporates.