Reference docs: Separate "library developer/user" content from "craft user" content
Metadata
Current evaluation
Reference docs remain a flat, mixed-audience index; Parts and Steps still combines permissions, environment, and output-directory material. The detailed restructuring proposal is open and untriaged.
Suggested action: needs triage
Reason: The issue has no labels, maintainer comments, or other triage signals. The current index is still flat, and parts_steps.rst still combines permissions, environment variables, and output directories, but the proposed audience-based hierarchy provides a concrete starting point; maintainers still need to approve names and placement.
Evaluated by: mr-cal-bot
Impact:
32
Quick Win:
14
Complexity:
42
Confidence:
93
Actionability:
76
Issue body
### What needs to get done
Looking at https://canonical-craft-parts.readthedocs-hosted.com/en/latest/reference/, the sub-sections have a different audience/content and are mixed:
* Actions: Python
* Exception: Python
* Project information: Python
* Lifecycle manager: Python
* Part properties: YAML
* Parts and steps: (contains 1 part property + build-time environment/directory information)
* Plugins: YAML
* Package reference: Python
* Changelog: Meta
"Parts and steps" is special:
* [permissions](https://canonical-craft-parts.readthedocs-hosted.com/en/latest/reference/parts_steps.html#permissions) should probably be moved to "Part properties"
* [steps](https://canonical-craft-parts.readthedocs-hosted.com/en/latest/reference/parts_steps.html#steps) could probably be split into a top-level "Environment variables" item (from "Step execution environment") and "Output directories" item (from "Step output directories")
It might make sense to have the "Environment variables" and "Output directories" as top-level items in the Reference section ("next to" Python, YAML and Changelog), since these are not directly related to either Python or YAML, but rather to the run-time shell scriptlets (those could then also be linked from the `*-override` docs, see #659).
Here's a proposed additional layer of structuring/grouping, e.g.:
* YAML
* Part properties
* Plugins
* ...
* Build
* Environment variables
* Output directories
* Python Library
* Actions
* Exception
* Project information
* Lifecycle manager
* Package reference
* ...
* Changelog
Instead of "YAML", maybe "Craft YAML", "Craft Language" or whatever exists as name for the `*craft.yaml` files might be used, of course. Also, moved the "Python Library" section to the bottom, since there's probably more "craft users" / end users than library users, so the YAML/Build parts should probably be presented more prominently.
### Why it needs to get done
When I'm using craft-parts as a Python library, I'm looking for different documentation than when I'm using craft-parts as an end user, and it's usually one or the other, seldomly both at the same time. Being able to drill down to the current "mode" I'm in will help avoid ending up on the wrong part of the documentation.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha |
Impact:
32
Quick Win:
14
Complexity:
42
Confidence:
93
Actionability:
76
|
needs triage | Reference docs remain a flat, mixed-audience index; Parts and Steps still combines permissions, environment, and output-directory material. The detailed restructuring proposal is open and untriaged. | |
| qwen/qwen3.6-35b-a3b |
Impact:
15
Quick Win:
9
Complexity:
15
Confidence:
75
Actionability:
70
|
needs triage | Documentation reorganization proposal to separate library developer content from craft user content in the reference docs. | |
| qwen/qwen3.8-27b |
Impact:
25
Quick Win:
14
Staleness:
70
Complexity:
45
Confidence:
72
Support Request:
0
|
needs triage | Request to restructure craft-parts reference docs by audience (craft YAML user vs Python library user) and split 'Parts and steps' into Environment variables / Output directories. Untriaged, no labels or comments; the flat structure still exists in current docs. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
92
Complexity:
35
Confidence:
75
Support Request:
5
|
needs triage | Proposes restructuring reference docs to separate library developer (Python) and craft user (YAML/Build) content. Currently unlabelled, zero maintainer comments, and inactive for over two years. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
85
Complexity:
15
Confidence:
80
Support Request:
10
|
needs triage | Proposal to restructure reference documentation by separating library developer content from craft user content. Unlabelled and has received no maintainer feedback in over a year. |
Update history
No update history recorded yet.
Related work
-
Related To:
craft-parts#659
(confidence 98%)
The issue explicitly links #659, which requests cross-references from override-step documentation to the environment and working-directory references that would be separated here.
Related issues
No related issues found above the similarity threshold.