docs(journeydoc): bootstrap capture-driven user documentation (ADR-030)#324
Merged
rubenvdlinde merged 1 commit intodevelopmentfrom May 6, 2026
Merged
docs(journeydoc): bootstrap capture-driven user documentation (ADR-030)#324rubenvdlinde merged 1 commit intodevelopmentfrom
rubenvdlinde merged 1 commit intodevelopmentfrom
Conversation
First adoption of the journeydoc pattern (defined in hydra/openspec/architecture/adr-030-journeydoc-pattern.md). Drops the 8-artifact scaffold: - `docs/tutorials/_category_.json` + per-track `_category_.json` for user-guide / admin-guide. - 8 user-track tutorial skeletons covering: first launch, add client, link contact person, move lead, log contact moment, capture request, sync with Nextcloud Contacts, resolve duplicate-detection warning. - 3 admin-track tutorial skeletons covering: pipeline stages, request types, user/group permissions. - `tests/e2e/docs-screenshots.spec.ts` capture-spec stub matching the tutorial-page filenames 1:1. - `playwright.config.ts` gains the `docs-capture` project (regression `chromium` project ignores the spec; capture project picks it up via `--project docs-capture`). Brown-field migration in the same PR: - Moved `docs/screenshots/` to `docs/static/screenshots/`. The old location was broken on production (Docusaurus only copies `static/*`); existing feature pages had silently-broken image refs for months. Image refs in `docs/features/*.md` rewritten from relative `../screenshots/...` to root-absolute `/screenshots/...`. - Docs domain moved from `pipelinq.app` to `pipelinq.conduction.nl` in three places: `docs/static/CNAME`, `docs/docusaurus.config.js` url, `.github/workflows/documentation.yml` cname. - Locale config trimmed from `['en', 'nl']` to `['en']`. Stale Dutch translation strings without translated markdown trigger SSR rendering failures (`Cannot read properties of undefined (reading 'id')`) — observed on mydash, fixed there in PR #134, applied here preemptively. - `markdown.hooks.onBrokenMarkdownImages: 'warn'` so a fresh checkout that hasn't run the capture spec yet still builds. Tutorial skeletons carry `{{TODO: ...}}` placeholders for the prose the team owns. Steps reference screenshots at the canonical `/screenshots/tutorials/<track>/<file>.png` paths; the capture spec populates them on `npx playwright test --project docs-capture`. Cross-references to `../../features/*.md` will warn during build for features that don't have reference pages yet (contacts, contact- moments, my-work, requests, duplicate-detection, permissions). Add those reference docs in a follow-up; the warnings don't block the build.
rubenvdlinde
requested review from
Rem-Dam,
SudoThijn,
WilcoLouwerse,
bbrands02,
remko48 and
rjzondervan
as code owners
Contributor
Quality Report — ConductionNL/pipelinq @
|
| Check | PHP | Vue | Security | License | Tests |
|---|---|---|---|---|---|
| lint | ✅ | ||||
| phpcs | ❌ | ||||
| phpmd | ✅ | ||||
| psalm | ✅ | ||||
| phpstan | ✅ | ||||
| phpmetrics | ✅ | ||||
| eslint | ❌ | ||||
| stylelint | ❌ | ||||
| composer | ✅ | ✅ 100/100 | |||
| npm | ❌ | ❌ | |||
| PHPUnit | ⏭️ | ||||
| Newman | ⏭️ | ||||
| Playwright | ⏭️ |
Quality workflow — 2026-05-06 14:06 UTC
Download the full PDF report from the workflow artifacts.
rubenvdlinde
added a commit
that referenced
this pull request
May 7, 2026
Companion to PR #324 (journeydoc bootstrap). Updates the README's documentation badge from `pipelinq.app` to `pipelinq.conduction.nl` and adds a one-line link to the tutorial site, with a reference to hydra's ADR-030 so future contributors know the journeydoc pattern exists.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First adoption of the journeydoc pattern from hydra ADR-030. Acts as the smoke test of the
journeydoc-initskill that just landed in hydra (PR #225).What landed
New tutorial structure
docs/tutorials/_category_.json+ per-track sidebarsEach page follows the canonical journeydoc shape (Goal → Prereqs → Steps → Verification → Common issues → Reference) with
{{TODO: ...}}placeholders for the prose the team owns.Capture spec + Playwright project
tests/e2e/docs-screenshots.spec.ts— one test block per tutorial, matching filenames 1:1playwright.config.tsgains thedocs-captureproject, regressionchromiumproject ignores the specBrown-field migration
docs/screenshots/→docs/static/screenshots/. The old location was silently broken on production (Docusaurus only copiesstatic/*). Feature-page image refs rewritten from../screenshots/...to/screenshots/....pipelinq.app→pipelinq.conduction.nlin CNAME + Docusaurus url + deploy workflow cname.['en', 'nl']to['en'](stale Dutch translations triggered SSR errors on mydash, fixed there in PR [customer-satisfaction] 5.1 Add Surveys menu item to navigation #134, applied here preemptively).markdown.hooks.onBrokenMarkdownImages: 'warn'so a fresh checkout still builds before the capture spec runs.Next steps after merge
pipelinq.conduction.nl→conductionnl.github.io. Existingpipelinq.appcert will continue to serve until DNS flips./journeydoc-instrumenton the high-traffic Vue components to add stabledata-testid="..."attributes. Capture-relevant surfaces: the client-create modal, the lead pipeline kanban cards, the contact-moment form, the My Work queue rows, the admin-settings sections./journeydoc-instrumenton the failing components.{{TODO: ...}}placeholders in the tutorial markdown.Test plan
docusaurus buildclean (warnings on cross-links to feature pages that don't exist yet — expected, those are TODOs in the skeletons)/screenshots/...conventionnpx docusaurus start) — verify navigation order, sidebar hierarchypipelinq.conduction.nldata-testids are addedPattern source
The exact templates this PR consumed live at
hydra/templates/journeydoc/. When the pattern evolves, those templates are the canonical reference.