### 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.