docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
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.
Suggested action: —
No scores available.
Issue body
Relevant tickets: ISD-4006, ISD-3973
Five changes to the 12-factor tutorials based on feedback from UX sessions.
### Summary of changes
* Reorder instructions for `rockcraft.yaml` setup -- have the user check the architecture of their host first, then take a look at the project file to determine if `platforms` matches their host.
* Rephrase the uploading of the rock.
* Put more commands into code blocks, specifically all `curl` commands and checking that the newly added Juju configuration appears in the list.
* Update the links in the "Next steps" table to align more closely with the expected user journey. This included adding a link to the 12-factor RTD site and updating links to be more 12-factor specific.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | 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. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes include reordered setup steps, improved command formatting, and updated navigation links. Reopened to resolve a test execution issue before final merge. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes include reordered setup steps, improved phrasing, added code blocks, and updated links. The request was reopened after spread tests initially failed. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #2354 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | 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. | |
| #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. | |
| #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. | |
| #2085 docs: update 12-factor tutorials | charmcraft | merged | Merged after converting the 12-factor tutorials to reStructuredText and incorporating UX feedback. Conflicts with PR #2083 were resolved via maintainer coordination before finalizing the merge. |