docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
Merged documentation updates to 12-factor tutorials based on UX feedback. Changes include switching code blocks to dropdowns, adding explicit paths, and clarifying MicroK8s and Juju setup. Approved by two reviewers and merged after CI validation.
Suggested action: —
No scores available.
Issue body
Relevant tickets: ISD-3755, ISD-3536, ISD-3541, ISD-3542, ISD-3543
Four changes to the 12-factor tutorials based on feedback from UX sessions.
### Summary of changes
* Participants regularly missed code snippets contained in `collapsed` blocks. They asked to expand all code snippets, but we will try using the `dropdown` element first to see if this resolves the issue.
* Add explicit paths to all code blocks and snippets in the tutorials.
* Explain the `sudo adduser` and `newgrp` commands when setting up MicroK8s.
* Explain the `mkdir` command when setting up Juju.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | Merged documentation updates to 12-factor tutorials based on UX feedback. Changes include switching code blocks to dropdowns, adding explicit paths, and clarifying MicroK8s and Juju setup. Approved by two reviewers and merged after CI validation. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes include replacing collapsed code blocks with dropdowns, adding explicit file paths, and clarifying MicroK8s and Juju setup commands. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes include converting code snippets to dropdowns, adding explicit paths, and clarifying MicroK8s and Juju setup commands. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2425 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged documentation updates to the 12-factor tutorials based on UX feedback. Changes include reordered setup steps, improved upload phrasing, added command blocks, and updated next steps links. Approved and passed CI. | |
| #918 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes clarify architecture, update multi-arch commands, refine terminology, and adjust setup. Approved by three reviewers and merged. | |
| #2387 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged documentation updates to the 12-factor tutorials based on UX feedback. Changes add a deploy intro, verify and destroy subsections, an achievements section, and fix PostgreSQL spelling. Approved by two reviewers with all CI checks passing. | |
| #2455 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes refine directory phrasing, remove explicit cd commands, and relocate code comments to main text. Approved by two reviewers and merged. | |
| #2445 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Edits clarify resources, ingress context, phrasing, environment variables, and database timing. Approved by two reviewers and passed CI checks. | |
| #956 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Merged documentation updates to 12-factor tutorials incorporating UX feedback. Corrects browser instructions, reorganizes commands, adds experimental extension variables, updates next steps, and adds intersphinx links. Approved by two reviewers and passed CI. | |
| #2463 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged documentation update incorporating UX feedback into 12-factor tutorials. Changes add an experimental extensions warning, restructure LXD setup steps, and clarify VM shell context. Approved by two reviewers and passed CI checks. | |
| #893 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Merged documentation updates incorporating UX feedback into 12-factor tutorials. Changes clarify skopeo usage, add file headers, correct Express and Spring Boot steps, and fix port values. All CI checks passed and reviewers approved the changes. | |
| #1006 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes clarify VM shell instructions, terminal closing steps, and rockcraft version warnings. Approved by two reviewers and passed CI checks. | |
| #2276 docs: Updates to the 12-factor tutorials | charmcraft | merged | Merged documentation updates across four 12-factor tutorials. Changes add rock and Juju model explanations, standardize instructional wording, and include context notes. Approved by reviewers and integrated. |