continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 128 Wiki Activity

docs(review): P1 fixes — sync slide-count metadata + README directory layout

Browse Source 
Review of P71 (v1.13) flagged 2 P1 documentation-metadata drift items:
1. Source .md length headers undercounted by 1 (excluded Appendix TOC slide)
2. README.md drifted — missing 12 new asset files + stale slide/section counts

Fixes:
- how-the-platform-works.md: 18 -> 19 slides (10 main + TOC + 8 appendix)
- the-developer-experience.md: 17 -> 18 slides (10 main + TOC + 7 appendix)
- both *-talking-points.md companion headers updated to match
- README.md directory layout: added 6 new .mmd + 6 new .png files
- README.md appendix convention: "10 main + 6 appendix (17 total)" ->
  per-deck counts (A1-A8 platform, A1-A7 developer, both with TOC)
- README.md current-decks table: slide counts updated to 19/18
- README.md talking-points structure: "10 main + 7 appendix" -> TOC-aware

No factual/capability claim changes. 16 docs tests pass.

---ci---
project: acdl
phase: 71
milestone: v1.13
status: verify
lessons:
  - P1 fix: sync slide-count metadata across source .md, talking-points, README
---/ci---
This commit is contained in:
Jon Chery
2026-07-29 14:51:27 +00:00
parent 7ea9a07be8
commit 06dea7a176
5 changed files with 27 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/presentations/README.md
+23 -9
View File
@@ -115,7 +115,7 @@ Distill the source of truth (Step 1) into presenter-ready cues, indexed by
the Marp deck (Step 2) slide structure:
- **One section per Marp slide** — `## Slide N — Title`, matching the Marp
deck's 10 main + 7 appendix slide structure exactly. The Marp deck
deck's 10 main + Appendix TOC + appendix slide structure exactly. The Marp deck
provides the indexing and context (what the audience sees); the source
markdown provides the content (the speaker notes, the detail, the nuance).
- **3-6 talking point bullets per slide** — punchy, actionable cues distilled
@@ -145,37 +145,49 @@ and re-distill.
docs/presentations/
├── README.md ← this file
├── how-the-platform-works.md ← Step 1: full source of truth
├── how-the-platform-works-marp.md ← Step 2: Marp deck (10 main + 7 appendix)
├── how-the-platform-works-marp.md ← Step 2: Marp deck (10 main + TOC + 8 appendix = 19)
├── how-the-platform-works.html ← Step 3: rendered HTML (committed)
├── how-the-platform-works-talking-points.md ← Step 4: presenter cues (16 sections)
├── how-the-platform-works-talking-points.md ← Step 4: presenter cues (19 sections)
├── the-developer-experience.md ← Step 1: full source of truth
├── the-developer-experience-marp.md ← Step 2: Marp deck (10 main + 7 appendix)
├── the-developer-experience-marp.md ← Step 2: Marp deck (10 main + TOC + 7 appendix = 18)
├── the-developer-experience.html ← Step 3: rendered HTML (committed)
├── the-developer-experience-talking-points.md ← Step 4: presenter cues (16 sections)
├── the-developer-experience-talking-points.md ← Step 4: presenter cues (18 sections)
└── assets/
├── puppeteer-config.json ← no-sandbox config for mmdc
├── mmd/ ← mermaid source files (Step 2 input)
│ ├── sp-theme.json ← S&P Red/Black/White theme (mermaid-cli --configFile)
│ ├── platform-works-01-contract-driven.mmd
│ ├── platform-works-02-frictions.mmd
│ ├── platform-works-02-end-to-end-flow.mmd
│ ├── platform-works-03-north-star.mmd
│ ├── platform-works-03-scope-boundary.mmd
│ ├── platform-works-04-confidence-signal.mmd
│ ├── platform-works-05-attestation-flow.mmd
│ ├── platform-works-07-zero-trust.mmd
│ ├── developer-experience-01b-scope-boundary.mmd
│ ├── developer-experience-02-what-dev-does.mmd
│ ├── developer-experience-03-no-cloning.mmd
│ ├── developer-experience-04-promotion-journey.mmd
│ ├── developer-experience-05-catalog.mmd
│ ├── developer-experience-07-decommission.mmd
│ ├── developer-experience-08-semver.mmd
│ └── road-to-north-star.mmd
└── png/ ← rendered PNGs (embedded in Marp)
├── platform-works-01-contract-driven.png
├── platform-works-02-frictions.png
├── platform-works-02-end-to-end-flow.png
├── platform-works-03-north-star.png
├── platform-works-03-scope-boundary.png
├── platform-works-04-confidence-signal.png
├── platform-works-05-attestation-flow.png
├── platform-works-07-zero-trust.png
├── developer-experience-01b-scope-boundary.png
├── developer-experience-02-what-dev-does.png
├── developer-experience-03-no-cloning.png
├── developer-experience-04-promotion-journey.png
├── developer-experience-05-catalog.png
├── developer-experience-07-decommission.png
├── developer-experience-08-semver.png
└── road-to-north-star.png
```
@@ -183,12 +195,14 @@ docs/presentations/
### Appendix structure
Each Marp deck has **10 main slides + 6 appendix slides** (17 total). The
Each Marp deck has **10 main slides + an Appendix TOC + appendix slides**. The
main 10 are the presentation; the appendix is for deep dives and Q&A backup.
The platform-works deck has 8 appendix slides (A1–A8); the developer-experience
deck has 7 appendix slides (A1–A7). Both include an Appendix TOC slide.
- **Main slides** (1-10): the story arc, high-impact, minimal text,
visual-heavy. These are what the audience sees during the talk.
- **Appendix slides** (A1-A5 + TOC): detail-heavy slides moved out of the
- **Appendix slides** (TOC + A1..An): detail-heavy slides moved out of the
main 10 to preserve the narrative flow. The appendix starts with a TOC
slide listing the contents, followed by detail slides and a glossary.
- **The Road to the North Star** is a required appendix slide in both decks
@@ -331,5 +345,5 @@ attachments to the Gitea release.
| Deck | Source of truth (Step 1) | Marp deck (Step 2) | Rendered HTML (Step 3) | Talking points (Step 4) | Slides | Audience |
|---|---|---|---|---|---|---|
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | `how-the-platform-works.html` | `how-the-platform-works-talking-points.md` | 10 main + 7 appendix | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | `the-developer-experience.html` | `the-developer-experience-talking-points.md` | 10 main + 7 appendix | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | `how-the-platform-works.html` | `how-the-platform-works-talking-points.md` | 10 main + TOC + 8 appendix (19) | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | `the-developer-experience.html` | `the-developer-experience-talking-points.md` | 10 main + TOC + 7 appendix (18) | CTO, Head of Cloud, Head of Infra, Head of DevOps |