Skip to content

docs(plans): explain test plans as a concept, not a yaml file - #19

Open
philipph-askui wants to merge 1 commit into
mainfrom
docs/test-plans-concept
Open

docs(plans): explain test plans as a concept, not a yaml file#19
philipph-askui wants to merge 1 commit into
mainfrom
docs/test-plans-concept

Conversation

@philipph-askui

Copy link
Copy Markdown
Contributor

What changed for the reader

The Test plans page currently opens with "A plan is a yaml file in `plans/`" and a yaml block, so it reads as documentation of a file format. A tester meets the storage detail before learning what the feature is.

This rewrite leads with the concept and the workflow instead:

  • Intro now says what a test plan is and what you do with it: a saved selection of tests and the device they run on, run with one click or on a schedule, with nothing inferring the selection.
  • Sections follow the journey: Build a plan (check tests + pick a device), Run it with one click, Put it on a schedule, Share it through Git.
  • The yaml example is demoted to a short "Under the hood: the plan file" section, framed as "you never edit it directly."
  • Older prose plans kept.

No behaviour claims changed. Everything here already shipped:

Verification

  • `npm run types:check` — green (MDX compiles, route types generate, `tsc --noEmit` clean).
  • All internal links resolve to real pages; the `#if-it-cant-start-right-away` anchor exists on the Running tests index. No #anchor elsewhere targets this page, so the heading restructure breaks nothing.
  • House style: no em dashes / interpuncts in prose; numbered click path for building a plan; bold-label bullet walkthroughs.

🤖 Generated with Claude Code

Lead with what a test plan is and what you do with it: a saved selection of
tests and the device they run on, built with checkboxes, run with one click,
and put on a schedule. The yaml is demoted to a short "under the hood" note
instead of being the first thing a reader sees.

Sections now follow the workflow (build, run, schedule, share via Git) so a
tester learns the feature without meeting the file format first. No behaviour
claims changed; all facts already shipped in integrated-task-platform#180.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant