How This Manual Was Generated

A record of the method, so it can be repeated for the student manual, re-run when BodhiTree changes, and judged on its merits.

The short version

Four parallel research agents read the codebase and wrote structured feature inventories. A single writer then turned those inventories into chapters, discarding anything that could not be traced to shipped code.

                    ┌─ Instructor screens scout ──┐
                    ├─ Backend/roles/flags scout ─┤
  Codebase  ────────┼─ Student screens scout ─────┼──── Synthesis ──── Chapters
                    └─ Plan-document miner ───────┘      (one writer)

Cost: roughly 1.3M tokens across the four agents, running 12–19 minutes each in parallel. Output: 12 documents, about 4,500 lines.

Why it was split this way

The four agents were not four equal slices of the same job. Each answered a different question, and the split is the part worth copying:

Agent	Question it answered	Why separate
Instructor screens	What buttons exist and what do they do?	The walkthrough backbone. Breadth-first over the UI tree
Backend/roles/flags	What is actually true about permissions and limits?	The UI lies about permissions — it renders buttons that the server rejects. Only the backend knows the real rules
Student screens	What do students see?	Became Appendix A. An instructor manual needs this to explain what a setting does
Plan-document miner	What are the exact formats and semantics?	`docs/*-plan.md` holds precise specs — CSV headers, grade formulas — that are painful to reverse out of code

Running them in parallel was worth it: the slowest took 19 minutes, so the research phase cost 19 minutes rather than an hour.

The one instruction that mattered most

The plan-document miner was told:

These are PLAN docs — some describe intent that never shipped. For every non-obvious claim, spot-check it against the actual code and label it VERIFIED (file:line) or PLAN-ONLY (not found in code). We must not document vapourware as working.

It came back with a 20-item list of features that exist only on paper. Without that instruction, the manual would confidently have documented:

Gradebook category weighting — the plan specifies “Multimedia Book (30%)”; the code computes a flat unweighted average. An instructor designing an assessment scheme around weights would have found out the hard way
Excel export of grades — CSV only
Exam enforcement for virtual labs — designed, never built. Documenting this could have caused an actual exam integrity failure
Backend deadline blocking on quiz resubmissions — only the browser enforces it
Single sign-on — endpoints exist, no button renders

Design documents are the most dangerous source for a user manual. They are written before the software, in the present tense, and they are never updated when scope is cut. Any documentation pipeline that reads them must verify every claim against shipped code.

The same check caught four stale statements inside the plan documents themselves — places where a document claimed something was unbuilt that had since been built. Those were reported back rather than silently used.

What made the output usable rather than merely accurate

Documenting absence. Every chapter ends with Known limitations, and §10.9 lists everything that does not exist. Time lost hunting for a feature that was never built is the most annoying kind of time to lose, and a generated manual is uniquely well placed to prevent it — the research already surfaced every “Coming Soon” placeholder and unimplemented button.

Quoting the software verbatim. Error messages, confirmation dialogs, and validation text are reproduced word for word. This makes the manual searchable by what a user is actually looking at: someone who sees “Preview expired. Please upload again.” can find it.

Mapping settings to consequences. Appendix A exists because instructors do not ask “what does show_marks_to_student do?” — they ask “why can’t my students see their marks?” The student-side research was reframed around instructor decisions.

Flagging the destructive paths. Replacing a quiz question file deletes all student submissions. The Recycle Bin silently does not cover two of the three activity types. These got prominent warnings because the interface’s own warnings are easy to click past.

What this method does not give you

Be clear about the limits before trusting it:

No screenshots. Code cannot produce them. See SCREENSHOTS.md.
It documents behaviour, not usability. The manual can say what a button does; it cannot say the workflow is confusing or suggest a better order of work. That requires watching someone use the software.
No task-frequency weighting. Every feature gets space roughly proportional to its complexity, not to how often it is used. A real instructor’s week is mostly three screens; the manual does not know which three.
Nothing is user-tested. No instructor has followed these steps on a live system. Treat the first version as a thorough draft, not a finished manual.
Reading code is not reading the deployment. Feature flags, platform settings, and premium plans vary per installation. This manual documents the standard production build.

The correct next step is a review pass by someone who teaches on BodhiTree, followed by capturing screenshots. That will find gaps this method cannot.

Repeating it

For the student manual

Re-run with the audience switched. The student screens research is already done — it produced a full inventory of every student screen, route, and empty state. The missing piece would be a scout for enrollment and self-service flows.

After BodhiTree changes

Do not regenerate the whole manual for a single feature change. Instead:

Run one scout scoped to the changed area, with the same VERIFIED / PLAN-ONLY discipline.
Update the affected chapter and its Known limitations section.
Check whether §10.9 needs a line removed — a “not available” entry becoming available is exactly the change users most want to know about.

Full regeneration makes sense roughly once a release, or after a large migration.

Prompt patterns worth reusing

For a screen inventory:

For each feature area: the URL route, what the user can concretely DO there (every button, tab, modal, bulk action), preconditions and gating, error and empty states, and file paths with line numbers. Be exhaustive on breadth — a long flat list beats a short summary.

For anything sourced from design documents:

Label every claim VERIFIED (file:line) or PLAN-ONLY. Anything you cannot verify, mark clearly — we must not document vapourware as working.

For the ground-truth pass:

Report anything user-visible that is broken, dead code, or dev-only, that we must NOT document as working.

That last prompt produced the single most valuable output of the whole exercise.

Honest assessment

Worked well: breadth and accuracy. Four agents covered a 60-app Django backend and a large React frontend in under 20 minutes, and caught contradictions between documentation and code that a human writer reading the same design documents would very likely have propagated.

Worked less well: judgement about what matters. The method produces even coverage, where a good manual is deliberately uneven — long on the three things people do daily, short on the rest. That shaping still needs a person who knows the audience.

The honest summary: this produced a strong, accurate, unusually complete first draft, and saved most of the research effort. It did not produce a finished manual, and publishing it without a teaching instructor’s review pass would be a mistake.