docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
Merged PR #918 as ddb5bbba, updating the 12-factor tutorials with UX feedback on architecture, setup, Multipass, multi-architecture commands, pack warnings, and terminology.
Resolution: closed resolved
Reason: The documentation PR was approved and merged into Rockcraft as commit ddb5bbba, changing 15 files to incorporate findings from UX sessions.
Evaluated by: mr-cal-bot
No scores available.
Issue body
Incorporate feedback from UX sessions into the 12-factor tutorials.
### Summary of changes
* cat rockcraft.yaml and update the architecture
* when updating the version, show a snippet of rockcraft.yaml to make it explicit
* Intro to the initial Rockcraft section explaining a rock better
* Make Multipass much more mandatory in the language
* More explanation in the setup section – copied over the text about Rockcraft
* Add the $(dpkg --print-architecture)where applicable to make the commands accessible to all architectures
* Emphasize-lines in code blocks where appropriate (didn’t see anything)
* Moved the LXD/Docker warning to the first pack attempt, and added another potential clue in the output
* Improved product terminology (removed code formatting for `npm` and `go` instances, converted some of the profile mentions to plain text, updated the Spring Boot tutorial title in the navigational menu)
- [X] Have you followed the guidelines for contributing?
- [X] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
- [x] Have you successfully run `make lint && make test`?
---
Successfully ran `make lint-docs`
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged PR #918 as ddb5bbba, updating the 12-factor tutorials with UX feedback on architecture, setup, Multipass, multi-architecture commands, pack warnings, and terminology. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged as ddb5bbba: revised the 12-factor tutorials with UX feedback, clearer architecture and setup guidance, multi-architecture commands, warnings, and terminology. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged as ddb5bbba, improving the 12-factor tutorials with UX-driven architecture, setup, packaging, multi-architecture, warning, and terminology guidance. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged #918: updated 12-factor tutorials with UX feedback, including architecture guidance, clearer setup and packaging steps, multi-architecture commands, and revised terminology. | |
| qwen/qwen3.6-35b-a3b | — | — | 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. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to the 12-factor tutorials based on UX feedback. Changes include clarified architecture, cross-architecture commands, updated terminology, improved setup instructions, and relocated LXD/Docker warnings. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #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. | |
| #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. | |
| #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). | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. |