docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
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.
Suggested action: —
No scores available.
Issue body
- [X] Have you followed the guidelines for contributing?
- [X] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
- [ ] Have you successfully run `make lint && make test`?
I ran `make lint` and received errors on files this PR doesn't touch.
---
Updates to the tutorials based on feedback in UX sessions:
1. When copying the skopeo command for the chiseled hello world rock. The user missed the hint to change the name in the project file to `0.1-chisel`, resulting in a error.
2. File headers could be added to file excerpts (app.py) [External example](https://www.digitalocean.com/community/tutorials/how-to-make-a-web-application-using-flask-in-python-3)
3. Clarification may be needed on what the skopeo command is doing. Maybe we could also mention about how Docker requires rocks (or images in general) to be imported into the daemon since they cannot be executed directly like an executable.
In addition, two corrections to the Express and Spring Boot tutorials:
1. Add `mkdir <app rock name>` and `cd <app rock name>` to the beginning of the tutorial so that the rock will have the correct name from the start.
2. Update the port to the correct value.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | 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. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to 12-factor tutorials incorporating UX feedback, command clarifications, and tutorial corrections. Unrelated CI test failures were rerun and resolved prior to final merge. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #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. | |
| #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. | |
| #2425 docs: Incorporate UX feedback into 12-factor tutorials | charmcraft | merged | 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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #1253 docs: Incorporate user feedback in the 12-factor reference pages | rockcraft | merged | Merged documentation updates to the 12-factor reference pages. Incorporates UXR feedback by improving headers, clarifying parts snippets and file inclusion rules, adding links and captions, and fixing acronyms. Approved and passed CI. |