← Back to issue list

docs: Incorporate user feedback in the 12-factor reference pages

View original Github issue

Metadata

Project
rockcraft
Number
#1253
Type
pull request
State
merged
Author
erinecon
Labels
documentation
Created
Updated
Closed

Current evaluation

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.

Suggested action:

No scores available.

Issue body

This PR updates the 12-factor reference pages to incorporate the following feedback received during UXR sessions: * Update the headers so that they’re human-readable and indicate the purpose or goal of the section * Clarify that the `parts` snippets are technically optional, but depending on the complexity of the project, could be required. Clarify when the user needs to add the snippet versus when they can safely ignore the snippet * Clarify the parts snippets that include or exclude files. Add this type of snippet overrides the default, and you exclude a file by including the snippet in your project file without the file. Add a reference for more complex ways of including or excluding files (e.g., with glob patterns) * Add more links (start script in the Express framework page, bare base, rocks, etc.) * Add captions to all code snippets so it’s clear that they touch the rockcraft.yaml project file. * Double check and clarify any undefined acronyms (e.g. WSGI in the Flask reference page). I successfully ran `make docs-lint` before opening the PR. I also did not add meta descriptions to avoid conflicts with https://github.com/canonical/rockcraft/pull/1246 --- - [x] I've followed the [contribution guidelines](https://github.com/canonical/rockcraft/blob/main/CONTRIBUTING.md). - [x] I've signed the [CLA](http://www.ubuntu.com/legal/contributors/). - [x] I've successfully run `make lint && make test`. - [x] I've added or updated any relevant documentation. - [ ] In documents I changed, I [added a meta description](https://canonical-starflow.readthedocs-hosted.com/how-to/add-a-page-meta-description/) if one was missing. - [ ] I've updated the relevant release notes.

Evaluation history

Date Model Scores Action Summary
qwen/qwen3.6-35b-a3b 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.
qwen3.6-35b-a3b-mtp-q6 Merged documentation updates to the 12-factor reference pages. Changes include human-readable headers, clarified parts snippet usage, file inclusion guidance, added framework links. Feedback addressed and lint passed before merge.

Update history

No update history recorded yet.

Related issues

Issue Project State Summary Similarity
#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.
84%
#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.
83%
#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.
83%
#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.
82%
#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.
82%
#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.
82%
#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.
81%
#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.
79%
#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.
78%
#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.
78%