docs(P44): leadership presentation decks + Marp synthesis + README
Add two leadership-facing presentation decks for senior leadership (CTO, Head of Cloud, Head of Infrastructure, Head of DevOps): 1. How the Platform Works — 14 slides covering the contract-driven model, zero-trust, computed safety, policy enforcement, secure-by-default, immutable audit, HITL, observability, platform-managed environments, portability, and an honest shipped-vs-planned roadmap. 2. The Developer Experience — 14 slides covering two consumer surfaces, the 5-line contract, no platform code, versioned releases, instant feedback, deploy outputs, local reproducibility, friendly onboarding, safe promotion (one contract + per-env CI jobs), safe decommission, self-service module catalog, and the leadership outcome. Each deck has two forms: - Full markdown (source of truth) with speaker notes + mermaid code blocks - Marp deck (lean, no speaker notes, embedded PNG diagrams) for presentation Includes a README documenting the 3-step slide creation process: (full markdown → Marp synthesis → PPTX export) with conventions, build commands, and maturity framing rules. ---ci--- phase: 44 milestone: v1.9 status: complete requirements: covered: [] partial: [] ---/ci---
This commit is contained in:
Jon Chery
@@ -0,0 +1,223 @@
|
||||
# Presentations
|
||||
|
||||
Leadership-facing presentation decks for the ACDL platform.
|
||||
|
||||
## The 3-step slide creation process
|
||||
|
||||
Every presentation in this folder is produced by the same three-step process.
|
||||
**Never edit the Marp deck or the PPTX directly** — always start from the full
|
||||
markdown source of truth (Step 1), synthesize the Marp deck (Step 2), then
|
||||
export to PPTX (Step 3). This keeps a reviewable, plain-text source of truth
|
||||
for every deck.
|
||||
|
||||
```
|
||||
Step 1: full markdown Step 2: Marp deck Step 3: PPTX export
|
||||
(source of truth) ──► (lean, no notes) ──► (presentation-ready)
|
||||
*.md *-marp.md *.pptx
|
||||
+ speaker notes + embedded PNG diagrams + embedded images
|
||||
+ mermaid code blocks + Marp frontmatter
|
||||
```
|
||||
|
||||
### Step 1 — Full markdown (source of truth)
|
||||
|
||||
**File convention:** `<deck-name>.md` (e.g. `how-the-platform-works.md`).
|
||||
|
||||
Write the complete deck as a standard markdown file. This is the **source of
|
||||
truth** — it contains:
|
||||
|
||||
- Every slide as an `## Slide N — Title` H2 section.
|
||||
- Tight bullets with leadership-relevant content.
|
||||
- A `> **Speaker notes:**` block at the end of each slide with the nuance,
|
||||
the "who cares and why," and the honesty caveats.
|
||||
- Mermaid diagrams as ```` ```mermaid ```` fenced code blocks (these render
|
||||
on GitHub/Pages but not in Marp — Step 2 converts them to images).
|
||||
- An honest "shipped vs. planned" framing: every "available today" claim is
|
||||
grounded in shipped/verified work; every "planned" item is explicitly
|
||||
marked.
|
||||
|
||||
**Why this file is the source of truth:** it is reviewable in any markdown
|
||||
viewer, diffs cleanly in git, and carries the full reasoning (speaker notes)
|
||||
that a presenter needs. The Marp deck and PPTX are *derived artifacts* — if a
|
||||
fact is wrong, fix it here and re-run Steps 2 and 3.
|
||||
|
||||
### Step 2 — Marp deck synthesis
|
||||
|
||||
**File convention:** `<deck-name>-marp.md` (e.g. `how-the-platform-works-marp.md`).
|
||||
|
||||
Synthesize the full markdown into a lean Marp deck:
|
||||
|
||||
- **Marp frontmatter** at the top: `marp: true`, `theme: default`,
|
||||
`paginate: true`, `size: 16x9`, a header/footer, and an inline `style:`
|
||||
block for fonts, colors, tables, badges.
|
||||
- **No speaker notes.** The Marp deck is what the audience sees; the
|
||||
speaker notes live only in the Step 1 source of truth.
|
||||
- **Mermaid diagrams → PNG images.** Marp does not render mermaid fenced
|
||||
blocks natively. Extract each mermaid block from Step 1 into a `.mmd`
|
||||
source file under `assets/mmd/`, render it to PNG under `assets/png/`,
|
||||
and embed it with ``.
|
||||
- **`<!-- _class: title -->` + `<!-- _paginate: false -->`** on title and
|
||||
closing slides for the dark-background title style.
|
||||
- **Maturity badges** using inline spans:
|
||||
`<span class="badge today">Available today</span>`
|
||||
`<span class="badge planned">Planned</span>`
|
||||
- **Tighter prose** than Step 1 — strip the speaker-note nuance; keep the
|
||||
leadership-relevant selling points.
|
||||
|
||||
### Step 3 — PPTX export
|
||||
|
||||
Export the Marp deck to PPTX for stakeholders who want a slide file:
|
||||
|
||||
```bash
|
||||
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @marp-team/marp-cli@latest --allow-local-files \
|
||||
docs/presentations/<deck-name>-marp.md \
|
||||
-o <output-path>.pptx
|
||||
```
|
||||
|
||||
The `--allow-local-files` flag is **required** for PPTX export so the local
|
||||
PNG diagrams are embedded in the file.
|
||||
|
||||
## Directory layout
|
||||
|
||||
```
|
||||
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
|
||||
├── the-developer-experience.md ← Step 1: full source of truth
|
||||
├── the-developer-experience-marp.md ← Step 2: Marp deck
|
||||
└── assets/
|
||||
├── puppeteer-config.json ← no-sandbox config for mmdc
|
||||
├── mmd/ ← mermaid source files (Step 2 input)
|
||||
│ ├── platform-works-01-contract-driven.mmd
|
||||
│ ├── platform-works-02-end-to-end-flow.mmd
|
||||
│ ├── developer-experience-01-two-surfaces.mmd
|
||||
│ ├── developer-experience-02-what-dev-does.mmd
|
||||
│ └── developer-experience-03-no-cloning.mmd
|
||||
└── png/ ← rendered PNGs (embedded in Marp)
|
||||
├── platform-works-01-contract-driven.png
|
||||
├── platform-works-02-end-to-end-flow.png
|
||||
├── developer-experience-01-two-surfaces.png
|
||||
├── developer-experience-02-what-dev-does.png
|
||||
└── developer-experience-03-no-cloning.png
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
### Maturity framing
|
||||
|
||||
Every capability claim in a deck is tagged with one of two badges:
|
||||
|
||||
| Badge | Meaning |
|
||||
|---|---|
|
||||
| `Available today` | Shipped and verified in the platform |
|
||||
| `Planned` | On the roadmap, not yet shipped |
|
||||
|
||||
This is non-negotiable for a leadership audience: never present a roadmap
|
||||
item as a current capability, and never bury a shipped capability's
|
||||
availability. When in doubt, check `.ciagent/ROADMAP.md` and the milestone
|
||||
status in `.ciagent/PROJECT.md`.
|
||||
|
||||
### Audience
|
||||
|
||||
The audience for these decks is **Senior Leadership**: CTO, Head of Cloud,
|
||||
Head of Infrastructure, Head of DevOps. The framing rules:
|
||||
|
||||
- **No jargon.** Translate internal terms: "primitives/modules" not "L1/L2",
|
||||
"intent" not "IR", "human attestation" not "HITL", "pattern" not
|
||||
"composition."
|
||||
- **Selling points forward.** Each slide leads with the leadership-relevant
|
||||
outcome; the mechanism follows.
|
||||
- **Zero-trust, security, observability, auditability, DX, citizen
|
||||
developer** are the themes — not implementation details.
|
||||
|
||||
### Diagrams
|
||||
|
||||
Mermaid diagrams in the Step 1 source use the repo's existing `flowchart`
|
||||
style (renders on GitHub/Pages). For the Marp deck (Step 2):
|
||||
|
||||
1. Extract the mermaid block into `assets/mmd/<deck>-<slide>-<name>.mmd`.
|
||||
2. Use **horizontal layouts** (`flowchart LR`) or **subgraph row-wrapping**
|
||||
for wide diagrams so the PNG fits a 16:9 slide without shrinking to
|
||||
illegibility. A 9-node sequential `flowchart TD` renders as a tall thin
|
||||
strip — restructure it as 2-row subgraphs or `flowchart LR`.
|
||||
3. Render with a 2x scale factor and transparent background for crisp slides.
|
||||
4. Embed with `` (or `h:320` for tall images).
|
||||
|
||||
## Build commands
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js + npx (for `@marp-team/marp-cli` and `@mermaid-js/mermaid-cli`)
|
||||
- A Chrome/Chromium binary (Marp PPTX export requires it)
|
||||
|
||||
This environment has a working Chromium at:
|
||||
`/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome`
|
||||
|
||||
### Render all mermaid diagrams to PNG
|
||||
|
||||
```bash
|
||||
cd docs/presentations/assets
|
||||
for f in mmd/*.mmd; do
|
||||
name=$(basename "$f" .mmd)
|
||||
PUPPETEER_EXECUTABLE_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @mermaid-js/mermaid-cli@latest \
|
||||
-i "$f" -o "png/$name.png" \
|
||||
-p puppeteer-config.json -s 2 -b transparent
|
||||
done
|
||||
```
|
||||
|
||||
The `puppeteer-config.json` passes `--no-sandbox` to the headless browser
|
||||
(required when running as root in this environment).
|
||||
|
||||
### Export a Marp deck to HTML (for browser preview)
|
||||
|
||||
```bash
|
||||
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @marp-team/marp-cli@latest \
|
||||
docs/presentations/<deck-name>-marp.md \
|
||||
-o <output-path>.html
|
||||
```
|
||||
|
||||
HTML export inlines images as base64 data URIs — no `--allow-local-files`
|
||||
needed.
|
||||
|
||||
### Export a Marp deck to PPTX (for stakeholders)
|
||||
|
||||
```bash
|
||||
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @marp-team/marp-cli@latest --allow-local-files \
|
||||
docs/presentations/<deck-name>-marp.md \
|
||||
-o <output-path>.pptx
|
||||
```
|
||||
|
||||
`--allow-local-files` is **required** for PPTX so local PNG diagrams are
|
||||
embedded in the file.
|
||||
|
||||
## Adding a new presentation
|
||||
|
||||
1. **Write the full markdown** as `<deck-name>.md` following the
|
||||
`## Slide N — Title` + `> **Speaker notes:**` structure. This is the
|
||||
source of truth.
|
||||
2. **Extract any mermaid diagrams** into `assets/mmd/<deck-name>-<slide>-<name>.mmd`
|
||||
and render them to `assets/png/` (command above).
|
||||
3. **Synthesize the Marp deck** as `<deck-name>-marp.md` with frontmatter,
|
||||
no speaker notes, embedded PNGs, and maturity badges.
|
||||
4. **Export to PPTX** with `--allow-local-files`.
|
||||
5. **Verify** the PPTX slide count and that media files are embedded:
|
||||
```bash
|
||||
python3 -c "
|
||||
import zipfile, re
|
||||
with zipfile.ZipFile('<output>.pptx') as z:
|
||||
slides = [n for n in z.namelist() if re.match(r'ppt/slides/slide\d+\.xml$', n)]
|
||||
media = [n for n in z.namelist() if n.startswith('ppt/media/')]
|
||||
print(f'{len(slides)} slides, {len(media)} media files')
|
||||
"
|
||||
```
|
||||
|
||||
## Current decks
|
||||
|
||||
| Deck | Source of truth (Step 1) | Marp deck (Step 2) | Audience |
|
||||
|---|---|---|---|
|
||||
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
|
||||
| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
|
||||
Reference in New Issue
Block a user