docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
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.
Suggested action: —
No scores available.
Issue body
Relevant ticket: ISD-4179
Five changes to the 12-factor tutorials based on feedback from UX sessions.
### Summary of changes
* Add a note in the "What you'll need" section to emphasize the importance of the required resources, specifically the RAM and disk space.
* Provide a bit more context about why we expose the app to ingress.
* Reword some awkward phrasing around changing directories and waiting for the app to be ready.
* Update the admonition block about configurations to clarify that the capitalization/prefix changes are made for the resulting environment variable. This is to help tie the concepts of app environment variables with charm configurations.
* Flask and FastAPI tutorials: Update the admonition block about adding `psycopg2-binary` in the `requirements.txt` file to clarify that adding the PostgreSQL database happens at the end of the tutorial.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | 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. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes clarify resource requirements, ingress context, phrasing, environment variable configuration relationships, and PostgreSQL setup timing. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to the 12-factor tutorials incorporating UX feedback. Changes clarify required resources, ingress context, directory navigation, environment variable configurations, and dependency installation steps. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. |