docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
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.
Suggested action: —
No scores available.
Issue body
Incorporate feedback from UX sessions into the 12-factor tutorials.
### Summary of changes
* Django and Express tutorials: The note about visiting the app in a browser was incorrect. This PR updates the notes to provide the correct instructions for visiting the app in a browser. I tested the instructions to verify that they work for my setup.
* Express tutorial: A participant noted that the `cd ..` command before initializing the rock was easily missed and caused issues for them during the session. This PR moves the command into the same code block that initializes the rock.
* FastAPI tutorial: Export `ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS` as an environment variable, identical to the other tutorials showcasing experimental extensions.
* All tutorials: Add or update the "Next steps" section to provide more relevant and useful links for the user looking for next steps, more information behind the extension or rocks, and to understand the "why" behind the 12-factor tooling.
* `conf.py`: Add intersphinx for the Charmcraft and 12-factor links in the "Next steps" sections of the tutorials.
- [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 successfully ran `make lint-docs` before opening this PR.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | 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. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged updates to 12-factor tutorials based on UX feedback. Fixes browser navigation instructions, reorganizes terminal commands, adds experimental extension environment variables, improves next steps links, and adds intersphinx references. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged PR updating 12-factor tutorials with UX feedback. Fixed browser instructions, reorganized commands, added experimental extension environment variable, and enhanced Next steps with better links and intersphinx configuration. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. |