← Back to issue list

docs: Incorporate UX feedback into 12-factor tutorials

View original Github issue

Metadata

Project
charmcraft
Number
#2425
Type
pull request
State
merged
Author
erinecon
Labels
—
Created
Updated
Closed

Current evaluation

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.

Resolution: closed resolved

Reason: The PR itself was merged into main as commit 17ce91b5 ("docs: Incorporate UX feedback into 12-factor tutorials (#2425)"), satisfying ISD-4006/ISD-3973. Review was approved by 2 reviewers; lengau's comment was only a note about closing and reopening the PR so the spread tests would run.

Evaluated by: mr-cal-bot

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
stealth/space-bunny-alpha — closed resolved 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.
stealth/space-bunny-alpha — closed resolved Merged UX-driven updates to the 12-factor tutorials, adding architecture-first setup guidance, clearer upload wording, formatted commands, and revised next-step links.
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.

Update history

No update history recorded yet.

Related work

  • Related To: canonical/charmcraft#2445 (confidence 70%)

    Follow-up PR with the same title continuing the UX-feedback pass over the 12-factor tutorials (commit 787f82c4).

  • Related To: canonical/charmcraft#2455 (confidence 70%)

    Further same-titled UX feedback PR merged as commit d31736f1.

  • Related To: canonical/charmcraft#2463 (confidence 65%)

    Subsequent same-titled UX feedback PR merged as commit 2820be49, continuing the tutorial docs work.

  • Related To: canonical/charmcraft#2387 (confidence 60%)

    Earlier iteration of the same 12-factor tutorial UX feedback series (commit 6368b845).

Related issues

Issue Project State Summary Similarity
#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).
90%
#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.
89%
#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.
89%
#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.
89%
#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.
87%
#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.
86%
#2354 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Merged UX-driven updates to the 12-factor tutorials: dropdown code snippets, explicit paths, and clearer MicroK8s and Juju setup commands.
85%
#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.
85%
#1253 docs: Incorporate user feedback in the 12-factor reference pages rockcraft merged Docs PR #1253 merged as commit 176cba44 into rockcraft main, applying UXR feedback to 12-factor reference pages (headings, parts snippets, include/exclude guidance, captions, acronym clarifications).
83%
#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.
80%