WeOwnAi/aibook-fun
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add content management and QA guide

Browse Source
This commit is contained in:
pat
2026-09-10 10:32:03 +00:00
parent 5c2bf88786
commit 686e13b2cd
1 changed files with 257 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
workflows/content-management.md
+257
View File
@@ -0,0 +1,257 @@
# Content management guide
How AiBook.fun content is written, reviewed, shipped, and kept current.
This is the operating guide for founding writers, Product, and anyone who touches a chapter before Kickstarter. The chapter blank is [`chapter-structure.md`](chapter-structure.md). Product decisions live in [`AiBook_PRD.md`](../AiBook_PRD.md) (§5 content model, §5.4 reading IA).
---
## 1. Source of truth
**Gitea is the CMS.** Canonical content lives as markdown under `workflows/` on [`WeOwnAI/aibook-fun`](https://git.weown.tools/WeOwnAI/aibook-fun).
| Role | Path |
|:--|:--|
| Chapter blank (do not fill this in place) | `workflows/chapter-structure.md` |
| One real chapter per vertical | `workflows/[vertical-slug].md` (example: `workflows/real-estate.md`) |
| Sample files shipped with a recipe | `workflows/samples/` or paths named in the recipe kit |
**Not canonical before Kickstarter**
- Notion pages
- A separate CMS or “edit on the live site”
- Hand-edited `marketing-site/data/sample-chapter.js` once a real markdown chapter exists (that file is demo residue)
Authors open a pull request. Reviewers merge to `main`. The reader and PDF read from that tree (directly or through a thin build step). Do not keep a second master copy.
---
## 2. What we are managing
**A chapter** is a substantial essay for one vertical. Full workflow recipes nest in the argument where they earn their place. Not an appendix. Not a shelf of cards.
**A workflow recipe** is the unit of practice. The reader reads it, runs the Try-it (~15 min) on sample data, and can share the result. Completing a Try-it is what counts as **activation**.
**Edition framing.** “2026 edition” / Edition 001 names the catalog year. Billing is `$47/yr`. Recipes are rewritten as tools and models change, often weekly or monthly. Do not describe the book as a once-a-year reprint.
**Public brand.** Write **AiBook.fun** (capital A, lowercase i). Domain `aibook.fun` stays lowercase.
---
## 3. Roles
| Role | Owns |
|:--|:--|
| Chapter owner (founding writer) | Draft, kit accuracy, Try-it that actually runs, PR |
| Product | Library sheet (IDs + owners), format gates, claims, merge readiness |
| Second reviewer (another writer or Product) | Structure checklist, safeguards, copy, claims language |
| Runner (author or named tester) | Executes the Try-it on the shipped sample files and records pass/fail |
One named human owns every Minimum Lovable Library workflow ID. No orphan recipes.
---
## 4. Verticals and IDs
| Vertical | Slug | ID prefix |
|:--|:--|:--|
| Real Estate | `real-estate` | `RE` |
| Financial Advisors | `financial-advisors` | `FA` |
| Fractional C-Suite | `fractional-c-suite` | `CS` |
| Higher Ed | `higher-ed` | `HE` |
| Communities | `communities` | `CM` |
| Technology | `technology` | `TE` |
**ID rules**
- Stable forever once published: `RE-01`, `FA-02`, and so on.
- Founding-library samples start at `01` per vertical unless a real catalog already assigned numbers.
- Do not reuse an ID for a different job. Bump recipe `version` when the steps change.
- URL / anchor form stays lowercase: `re-01` for heading anchors.
Keep a short **library sheet** (issue or markdown table on `main`) with: ID, short title, chapter file, owner, status (`draft` / `in review` / `shipped`), last Try-it date.
---
## 5. Day-to-day process
### 5.1 Assign
1. Product puts the vertical and recipe IDs on the library sheet with a chapter owner.
2. Owner copies `workflows/chapter-structure.md` to `workflows/[vertical-slug].md`.
3. Replace `XX` with the vertical prefix. Delete unused recipe slots. Do not leave hollow blocks.
### 5.2 Draft
Write in this order so safeguards are not an afterthought:
1. Chapter promise and Skip-to-Try-it links
2. What you need (union of kits)
3. Essay sections that earn the first workflow
4. Each nested recipe: **Kit → Problem → Actors → Setup → Safeguards → Method → Evidence → Try-it → Share → Record**
5. Essay continues between recipes where needed
6. Further workflows and Sources
Rules that do not move (from the blank / PRD §5.4):
- Skip-to-Try-it at the top
- Safeguards before Method
- Method shows real tool output, not a paraphrase
- Nested recipes stay open (no click-to-reveal Method)
- Every recipe has a kit and a stable ID
- No chatbot on the page
- No crypto, Web3, NFT, or token language
- PDF must match the web stack: essay + in-place recipes
### 5.3 Kit (required on every recipe)
Inventory, not instructions. Setup still explains how to use the items.
- You run
- Tools (named; versions if it matters)
- Files (sample files we ship)
- Model
- Time
- Cost (sample-run amount, or “unknown”)
- You produce (the artifact)
### 5.4 Run before you ask for review
The author or a named runner:
1. Uses only the sample files named in the kit (no live client data)
2. Follows Safeguards, then Method
3. Finishes the Try-it in about the stated time
4. Produces the named artifact
5. Notes model, token/cost if known, and any step that failed
A recipe that has not been run on its own samples is not ready for merge.
### 5.5 Pull request
- Branch from `main`
- One chapter file per PR when possible (samples can land in the same PR)
- PR description lists: recipe IDs touched, who ran the Try-it, date, pass/fail, cost if known
- Link the library sheet row(s)
### 5.6 Review and merge
Second reviewer completes the QA checklist below. Product confirms claims language and ID stability. Merge to `main` only when the checklist is green.
### 5.7 After merge
- Update the library sheet status and last Try-it date
- Reader / PDF consume `main` (demo JS is not updated by hand as a second source)
- When tools break a step, open a PR that fixes Method and bumps `version`. Do not wait for a yearly reprint.
### 5.8 Ongoing updates
As models and products change:
1. Owner reproduces the break on current tools
2. Patches Method, kit, cost, and sample output
3. Re-runs the Try-it
4. Merges; notes “currency fix” in the PR
---
## 6. Quality assurance
QA has three layers. All three are required to ship.
### 6.1 Structure QA (can fail the PR in review)
- [ ] File is `workflows/[vertical-slug].md`, not an edit of `chapter-structure.md`
- [ ] Front matter: vertical, title, authors, `recipe_ids`, `last_updated`
- [ ] Skip-to-Try-it links resolve to recipe anchors
- [ ] What you need matches the union of recipe kits
- [ ] Each recipe ID matches the library sheet and the vertical prefix
- [ ] Order inside each recipe: Kit, Problem, Actors, Setup, Safeguards, Method, Evidence, Try-it, Share, Record
- [ ] Safeguards appear before Method
- [ ] Method includes real tool output (fenced block or equivalent), not only prose
- [ ] Kit fields are all filled; tools and files are named
- [ ] Try-it names sample data, artifact, and done-when
- [ ] No chatbot; no crypto / Web3 / NFT / token language
- [ ] Brand spelling is AiBook.fun in any product-facing sentence
### 6.2 Run QA (required evidence in the PR)
- [ ] Try-it executed on the shipped sample files only
- [ ] Completed in roughly the stated time (±5 min is fine; flag large misses)
- [ ] Artifact produced matches “You produce”
- [ ] Safeguards held (no live client identifiers in prompts)
- [ ] Cost or token note recorded, or explicitly marked unknown
- [ ] Failure modes in Safeguards still match what happened in the run
### 6.3 Editorial and claims QA
- [ ] Chapter title and promise are plain facts, not slogan copy (“not X, but Y”)
- [ ] Stakes name a real failure in this vertical
- [ ] Actors separate what the model may do from what a human must do
- [ ] Evidence is an artifact or number, not “the user felt more confident”
- [ ] Share line shares the outcome, not the recipe text
- [ ] Any figure that could appear on Kickstarter or the marketing site is on the claims register or removed
- [ ] Pricing language matches signed decisions: `$47/yr`, no lifetime SKU as an equal v1 product
- [ ] Contribution / “stake” language matches D-2 / D-6 (authored v1; paid contribution is Layer 2; no token ownership claims)
### 6.4 Reader QA (before a chapter is linked from `/read` or the campaign)
- [ ] Chapter opens from the Library with correct breadcrumb
- [ ] Skip-to-Try-it and in-chapter outline jump to the right anchors
- [ ] Kit shows on the chapter and on each nested recipe
- [ ] Mark-complete / activation demo still works if that surface is live
- [ ] Print / focus view matches the nested recipe content
---
## 7. Definition of done
A workflow is **shipped** when:
1. It has a stable ID and named owner on the library sheet
2. It lives in a merged chapter file on `main`
3. Structure QA, Run QA, and Editorial QA all passed
4. A second person signed the review (PR approval is enough)
A chapter is **preview-ready** (backer sample) when at least two nested workflows are shipped inside it and Reader QA passed.
The **Minimum Lovable Library** floor is 15–20 shipped workflows across at least three verticals, each with a named author (Gate 0 / Implementation Plan).
---
## 8. Claims and public surfaces
Anything that can appear on Kickstarter, the marketing site, email, or social:
- Must match merged content or the signed product decisions
- Must not invent activation rates, contributor counts, or ownership language
- Goes through the claims register when Product opens it
Marketing site copy points at the Library. It does not become a second place to maintain recipes.
---
## 9. Quick start (one chapter)
```text
1. Copy workflows/chapter-structure.md → workflows/real-estate.md
2. Fill RE-01 and RE-02 (kit first, then safeguards, then method with real output)
3. Add sample files named in the kits
4. Run both Try-its; note results in the PR
5. Open PR → second reviewer runs §6 checklists → merge
6. Update library sheet; link chapter from the reader when the build path is ready
```
---
## 10. Related files
| File | Why |
|:--|:--|
| [`workflows/chapter-structure.md`](chapter-structure.md) | Blank chapter + recipe shape |
| [`AiBook_PRD.md`](../AiBook_PRD.md) | Content model, reading IA, activation |
| [`AiBook_Spec.md`](../AiBook_Spec.md) | Spec detail |
| [`AiBook_Implementation_Plan.md`](../AiBook_Implementation_Plan.md) | MLL floor, Gate 0, content critical path |
| `marketing-site/pages/read/` | Reading demo only until markdown feed exists |
**Last updated:** 10 Sep 2026