docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
Merged UX-driven updates to the 12-factor tutorials: dropdown code snippets, explicit paths, and clearer MicroK8s and Juju setup commands.
Resolution: closed resolved
Reason: PR #2354 was merged as commit 06ec43fb. It updated six files with dropdown-based snippets, explicit file paths, and explanations of sudo adduser, newgrp, and mkdir.
Evaluated by: mr-cal-bot
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 |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged UX-driven updates to the 12-factor tutorials: dropdown code snippets, explicit paths, and clearer MicroK8s and Juju setup commands. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged canonical/charmcraft#2354 as commit 06ec43fb, improving 12-factor tutorials with dropdown snippets, explicit paths, and MicroK8s/Juju command explanations. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged canonical/charmcraft#2354 via commit 06ec43fb, updating 12-factor tutorials with dropdown code snippets, explicit paths, and MicroK8s/Juju command explanations. | |
| 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. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #918 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Merged PR #918 as ddb5bbba, updating the 12-factor tutorials with UX feedback on architecture, setup, Multipass, multi-architecture commands, pack warnings, and terminology. | |
| #893 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Merged as 9a40a4a3, updating 12-factor tutorials with clearer skopeo guidance, file headers, and corrected Express and Spring Boot setup instructions. | |
| #2387 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Docs-only PR merged (commit 6368b845): applied UX session feedback to the 12-factor tutorials — added Deploy intro, Verify/Destroy app steps, an achievements section, and a PostgreSQL spelling fix (+125/-81, 5 files). | |
| #2445 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged PR #2445 as commit 787f82c4, updating six 12-factor tutorial files with UX feedback on resources, ingress, configuration, wording, and PostgreSQL setup. | |
| #2455 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Docs-only PR merged to main as commit d31736f1, applying UX-session feedback (ISD-4286) to the 12-factor tutorials: reworded the project-directory cleanup step, removed explicit cd commands, and moved code-block comments into prose. | |
| #2425 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged docs PR applying UX-session feedback to the 12-factor tutorials (commit 17ce91b5, 8 files, +349/-207): reordered rockcraft.yaml arch steps, reworded rock upload, code-blocked curl/config commands, and refreshed next-step links. | |
| #2463 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | Merged PR #2463 updated 12-factor tutorials with experimental-channel guidance, reordered LXD setup, and clarified that subsequent commands run inside the VM. | |
| #956 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Docs-only PR merged as commit c28f1197:12-factor tutorials updated with UX feedback — corrected browser visit instructions, Express 'cd ..' moved into the init rock block, FastAPI experimental extension env var, expanded Next steps, and intersphinx links in conf.py. | |
| #1006 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | Merged PR #1006 in commit 9aec04c7, clarifying VM command context, terminal shutdown, and rockcraft pack overwriting when rock versions are unchanged. | |
| #2085 docs: update 12-factor tutorials | charmcraft | merged | Merged in #2085 (79fa5ad9), updating 12-factor tutorials to rST, incorporating UX feedback, and standardizing content after #2083. |