docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
Merged PR #2445 as commit 787f82c4, updating six 12-factor tutorial files with UX feedback on resources, ingress, configuration, wording, and PostgreSQL setup.
Resolution: closed resolved
Reason: PR #2445 was approved and merged into the main branch as commit 787f82c4, delivering the requested tutorial documentation improvements.
Evaluated by: mr-cal-bot
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 |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged PR #2445 as commit 787f82c4, updating six 12-factor tutorial files with UX feedback on resources, ingress, configuration, wording, and PostgreSQL setup. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged #2445 as commit 787f82c4, updating 12-factor tutorials with UX feedback on resources, ingress, configuration, phrasing, and database setup. | |
| 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. |
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 | 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). | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. |