diff --git a/docs/specs/006-learning-paths/plan.md b/docs/specs/006-learning-paths/plan.md new file mode 100644 index 0000000..50553c4 --- /dev/null +++ b/docs/specs/006-learning-paths/plan.md @@ -0,0 +1,41 @@ +# 006 — Plan + +## Data +`_data//learning-paths/.yaml`: +```yaml +title: Frontend development +summary: From HTML and CSS to a component framework and testing. +subcategory: development/frontend-development +level: beginner +source: ipl +stages: + - title: Foundations + steps: + - title: How the web works + summary: Requests, responses, browsers and URLs. + resources: [https://developer.mozilla.org/...] +see_also: + - name: Frontend Developer Roadmap (roadmap.sh) + url: https://roadmap.sh/frontend +``` + +## Generation +`_plugins/learning_paths.rb` (a Jekyll Generator) creates one page per path and one index page per language, using +`_layouts/learning-path.html`. It resolves each step URL to its curated entry (name, description, access); an unknown +URL fails the build in development and test. + +## Interaction +`assets/js/learning-path.js` (vanilla, no dependencies), loaded only on path pages: +- `
` per step, so it works without JS; +- checkboxes stored under `ipl:path::`, with a progress bar that has `aria-valuenow`; +- a polite live region that announces progress. + +## Authoring +Paths are drafted by agents from IPL's own data: the subcategory's sections and its curated resources. The prompt +forbids consulting external roadmaps. Claude reviews order, wording and resources, and native-language drafts are +written for pt-BR. + +## Tests +- `test/learning_paths_test.rb`: schema, the resource URLs exist, `source: ipl`, both languages present. +- Build test: the pages render and the subcategory page lists its paths. +- e2e: progress persists across reloads; axe passes. diff --git a/docs/specs/006-learning-paths/spec.md b/docs/specs/006-learning-paths/spec.md new file mode 100644 index 0000000..f04a168 --- /dev/null +++ b/docs/specs/006-learning-paths/spec.md @@ -0,0 +1,39 @@ +# 006 — Interactive learning paths + +Status: draft · Depends on: 002 (curated resources) + +## Why +Readers ask "where do I start, and what comes next?". IPL already has thousands of curated resources per topic but no +order through them. A learning path turns a topic into ordered steps, each backed by IPL's own resources, and lets +readers mark progress. + +## What +1. **Paths as data.** One file per path: `_data//learning-paths/.yaml` with `title`, `summary`, + `subcategory` (where it is listed), `level` (beginner, intermediate or advanced), `steps`, and optional `see_also`. +2. **Steps.** Each step has a `title`, a short `summary` written for IPL, 2–5 `resources` (URLs that already exist in + IPL's curated data), and optional `optional: true`. Steps may group into `stages`. +3. **Pages.** `//learning-paths/` lists every path. `//learning-paths//` shows one path: + - stages and steps in order, expandable; + - the resources of each step, linking to IPL's entries; + - a progress checkbox per step and a progress bar, kept in the reader's browser (localStorage, no account); + - links to related paths and to external roadmaps listed under `see_also`. +4. **Discoverability.** Subcategory pages show their paths above the curated resources. Search indexes path and step + titles. +5. **Languages.** en-US and pt-BR, with steps written natively in each language. + +## Original content and credit +Paths are authored for IPL from IPL's taxonomy and curated resources. They are not copied, translated or adapted +from roadmap.sh or any other roadmap: that content is licensed for personal use only. External roadmaps appear only +as links under `see_also`, credited by name. + +## Acceptance criteria +- [ ] At least 12 paths per language at launch, covering the most visited development and computing subcategories. +- [ ] Every step resource URL exists in IPL's curated data (test). +- [ ] Without JavaScript, the path is a readable ordered list. With JavaScript, steps expand and progress persists + across reloads. +- [ ] Keyboard and screen-reader accessible: checkboxes are labelled and progress is announced. axe reports no + serious or critical issues. +- [ ] No content copied from external roadmaps. Each path records its authorship in `source: ipl`. + +## Out of scope +Accounts, server-side progress, quizzes, certificates, graphical node maps. diff --git a/docs/specs/006-learning-paths/tasks.md b/docs/specs/006-learning-paths/tasks.md new file mode 100644 index 0000000..d467b3b --- /dev/null +++ b/docs/specs/006-learning-paths/tasks.md @@ -0,0 +1,9 @@ +# 006 — Tasks + +- [ ] T1 Data schema and test (`test/learning_paths_test.rb`) +- [ ] T2 Generator, layout and index page (en-US, pt-BR) +- [ ] T3 Interaction script: details, progress, live region; no-JS fallback +- [ ] T4 Subcategory pages list their paths; search indexes paths +- [ ] T5 Author 12 paths per language from IPL data (frontend, backend, Python, JavaScript, data analysis, machine + learning, DevOps, cybersecurity, databases, UX, mobile, computer science), with reviews +- [ ] T6 e2e and axe checks