Skip to main content

Publishing checklist

A workshop ships when every item below is true, not when the last lab is written. The checklist at the bottom stores your ticks in this browser, so you can work through it over several days. The sections above it say how to check each item.

Facts, checked and dated​

Every command, flag, path, settings key, event name and exit code must trace to the fact sheet, and the fact sheet must trace to the docs on a known date.

  • Rebuild reference/factory-facts.md from the current docs no more than two weeks before launch. Put the date at the top.
  • Set docsCheckedOn in customFields.academy to the same date. The scenario page and the overview say it in prose too. Update them.
  • Search every page for product facts that aren't in the sheet. The quickest way: pick ten commands at random and find each one in the sheet. If one is missing, check them all.
  • Re-read the "contradictions" section of the fact sheet. Where Factory's own pages disagree (Workshop 01 had five), the lab should say so and tell the learner what to check.
  • Run the fact-sheet commands yourself on the pinned Droid version: droid --version, droid exec --help, droid rules check. Help text beats memory.

The build​

  • Run node scripts/check-mdx.mjs with no arguments. It checks every file under docs/: MDX compiles, every component is registered, every relative link resolves. Fix everything it reports.
  • Then run the full Docusaurus build, once, with nobody else editing. The config sets broken links to throw, so a clean build means no broken internal links.
  • Click through every playground page. They run client-side and the build doesn't exercise them.
  • Open the site at phone width. Tables and transcripts should scroll inside their own box, not push the page sideways.

The pilot, and real numbers​

Until the pilot, every scoreboard figure, transcript and receipt is illustrative, and the site says so. The pilot is how that changes.

  • Run the whole workshop end to end with at least five people who match the audience, on the pinned Droid version.
  • Record the facilitator's full scoreboard after every lab with npm run scoreboard -- --json. Keep the JSON files.
  • Replace the passes in src/data/scoreboard.ts with the measured numbers. Rewrite each snapshot's note to match what actually happened. If the shape differs from the illustrative story, change the labs to match the evidence. Don't adjust the evidence to match the labs.
  • Replace transcripts and receipts with recorded sessions. Open each session with droid --resume <session-id> and copy what happened.
  • Only then set numbersAreIllustrative to false, and pass illustrative={false} on each transcript and receipt that is now real. Anything you didn't replace keeps its badge.
  • Check the scoreboard badge. In this draft, <Scoreboard> and <ScoreboardDelta> always show it and nothing reads numbersAreIllustrative yet. Wire the flag through before launch, or the real numbers will still say "Illustrative".
  • Time every lab in the pilot. Update minutes in src/data/labs.ts and the run of show.

Accessibility​

  • Every image has alt text, or an empty alt if it's decorative.
  • Headings go in order, with no skipped levels. Each lab has one h1.
  • Nothing depends on color alone. Protected paths in <FileTree> carry a text tag, and scoreboard cells show 2/3, not just a color.
  • Every interactive element works with a keyboard: knowledge checks, checkpoints, playgrounds, the copy buttons.
  • Check contrast in light and dark mode.
  • Videos have captions and a transcript.
  • Link text says where it goes.

The video​

  • Record one narrated walkthrough per lab after the pilot, on the pinned version, using the pilot's real sessions.
  • Add chapters and captions.
  • Set youtubeId, duration and chapters on each <LabVideo>. Until then it shows "Recording coming soon", which is honest.
  • Record the two-minute introduction for the home page.

Teaching material​

  • Facilitator keys written for every <Q> in every lab: a model answer, the common wrong answer, and what to say when you hear it.
  • Instructor guide covers setup, pacing, the scoreboard budget, and how to replace illustrative numbers.
  • Run of show has a full day, a half day and a talk, each with a cut for when the room falls behind.
  • Solutions exist for every lab and match the companion repo's harness-reference/ exactly.
  • The companion repo is public at the URL in customFields.academy, its tests pass, and npm run scoreboard -- --dry-run works on a fresh clone.

A feedback route​

  • /feedback submits the internal feedback form: it saves the record to MongoDB and emails a workshop administrator. Check that a test submission is saved and that the notification reaches PRIMARY_ADMIN_EMAIL, and that a failed notification can be retried from the /admin feedback view.
  • feedbackIssueUrl now backs only the optional secondary "open a GitHub issue" link on /feedback; if you keep it, check the link opens the intended repository.
  • discussionsUrl points at a discussions board that is turned on, with a pinned welcome post.
  • Confirm an active administrator can review, resolve, and export feedback in /admin before the workshop runs.

The checklist​

Checkpoint0 / 12

If a skeptical staff engineer read only the scoreboard and one lab, would anything on either page be untrue?