docs: Tutorial updates
Metadata
Current evaluation
Merged tutorial updates based on UX feedback. Changes clarify architecture YAML, explain the PostgreSQL blocked state, and simplify teardown instructions. Approved by three reviewers with 78 additions and 52 deletions.
Suggested action: —
No scores available.
Issue body
Three updates that expand over all four tutorials. These changes were suggested from one or more UX sessions.
Summary of changes:
1. If the user needs to open rockcraft.yaml or charmcraft.yaml to update the architecture to `arm64`, have them also comment out `amd64`. While there's no harm or issue with having both architectures available, for novice users, this change will eliminate any possible concern or worry over including both architectures in the YAML file(s).
2. Provide more explanation and reassurance about the web app entering a blocked state when adding the PostgreSQL database.
3. Rephrase the "tear things down" section to tell the users that they can just delete the whole instance if they're not going to keep the VM.
Additional reviewer: @jdkandersson
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | Merged tutorial updates based on UX feedback. Changes clarify architecture YAML, explain the PostgreSQL blocked state, and simplify teardown instructions. Approved by three reviewers with 78 additions and 52 deletions. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates for four tutorials based on UX feedback. Changes clarify YAML architecture settings, explain the PostgreSQL web app blocked state, and simplify VM teardown instructions. Reviewed by @jdkandersson. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged tutorial documentation updates based on UX feedback. Changes clarify architecture YAML configuration, explain the PostgreSQL blocked state, and simplify VM teardown instructions. Approved by @jdkandersson. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #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. | |
| #6316 docs: improve tutorial based on user testing | snapcraft | merged | Merged documentation improvements to the tutorial based on user experience research feedback. Approved by one reviewer, passed CI checks, and modified two files to refine the guide. | |
| #6231 docs: incorporate tutorial feedback | snapcraft | merged | Merged documentation updates incorporating tutorial feedback from UXR and a TA. Approved by three reviewers and passed CI checks. Modified four files (+53/-72 lines) to refine project guides. | |
| #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. | |
| #5422 docs: add tutorial | snapcraft | merged | Merged a new documentation tutorial authored by maintainer medubelko. Approved by two reviewers and passing CI, the change adds 795 lines across 10 files to introduce the updated guide. |