grafana / grafana/interactive-tutorials
Create internal Learning Hub course: Block Builder for interactive learning paths
- Dominant language
- HTML
- Stars
- 13
- Forks
- 8
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 45
Description
## Summary
Create an internal Learning Hub course that teaches the doc team how to use Block Builder to create and test interactive learning paths.
Parent: #404
## Audience
Grafana Documentation team writers with little or no prior Pathfinder experience.
## Deliverable
A self-contained Learning Hub course (internal) that walks writers through the full Block Builder workflow for learning paths — from importing `content.json` to validating every interactive step before merge.
## Course should cover
### Block Builder basics
- Where to access Block Builder (`learn.grafana.net/?pathfinder-dev=true`)
- How to import a milestone `content.json` for local testing
- **Show me** vs **Do it** behavior and when to use each
### All block types
Demonstrate each block type with a worked example and visual (screenshot or short recording):
- Content: `markdown`, `html`, `image`, `video`
- Interactive: `interactive`, `multistep`, `guided`, `code-block`
- Structural: `section`, `conditional`, `assistant`, `grot-guide`
- Assessment: `quiz`, `input`
- Terminal (if applicable to LP authors): `terminal`, `terminal-connect`
Reference: `docs/json-guide-reference.md`
### PR review tool
- When to use Block Editor import vs the PR review tool (pathfinder-app 1.4.5+)
- How to open dev tools → **PR review tool** and load milestone JSON from an open PR
- Testing one milestone at a time at the correct `startingLocation`
- What to report when a step fails (wrong highlight, Do it doesn't click, etc.)
### Gotchas and troubleshooting
- Selector stability (`data-testid`, navmenu-open, lazyRender for virtualised lists)
- Common failures: missing `exists-reftarget`, `on-page` requirements, focus-before-formfill
- Testing across multiple stacks/environments (not only `learn.grafana.net`)
- When to mark a selector `TODO:manual-review` vs keep iterating
- `business-value` milestone is markdown-only (no interactive blocks)
### Related workflow context
- How Block Builder testing fits into the broader LP workflow (`/create-learning-path`, `/build-interactive-lj`, `/preflight-learning-path`)
- Link to the writer one-pager (#405) once it exists
## Acceptance criteria
- [ ] Course published to internal Learning Hub
- [ ] Every block type demonstrated with at least one visual
- [ ] PR review tool section includes step-by-step setup and a test walkthrough
- [ ] Gotchas/troubleshooting section covers the top failure modes from LP review
- [ ] Course is scoped for doc writers (not Pathfinder developers)
- [ ] Linked as a sub-issue of #404
## References
- `docs/json-guide-reference.md` — block types
- `docs/interactive-actions.md` — action behavior
- `docs/selectors-and-testids.md` — selector patterns
- `.cursor/learning-path-workflows/workflows.md` — Phase 4 testing workflow
- `.cursor/skills/preflight-learning-path/author-testing.md` — author Block Editor testing
- `.cursor/skills/review-learning-path/SKILL.md` — PR review tool (reviewer side)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.