Split contribution docs into an isolated subsection and unify all Nix contribution docs into one site
lf- opened this issue · comments
Observations
Currently nixpkgs, nix and the docs team have separate contribution information areas. Currently they use CONTRIBUTING files which can get long and don't necessarily have nice space for presenting justification or vision, which leads to contributor burnout due to lack of value alignment leading to bike shedding.
Problem
There's not a lightweight to edit place for contribution docs that's centralized, has nice navigation, and working search.
Approaches
infinisil noted that it would be preferable to keep docs inside nixpkgs. I have no horse in this race; if we link it well it's probably fine regardless of where the files go.
The central idea of this is creating a place like the rustc developer book which is easy to edit (not quite a wiki but more chill than official docs) and hopefully stays up to date; it provides explanations of how internals work, high level architecture explanations, and reasoning for things. https://rustc-dev-guide.rust-lang.org/
Willing to help?
Maybe, feels like this might itself die to the bike shed and I'm afraid to touch it.
Priorities
Add 👍 to issues you find important.
NixOS/nixpkgs#270696 (comment)
this is an example of a contribution that the contributor didn't know the right place to put it and would have benefited from a high level view of where stuff goes. i believe we have one but it's not in the path where we look for things as contributors.
I think these are two issues:
- Sort the various documentation types into their places (editorial)
- Make a unified presentation (technical)
It seems the @NixOS/documentation-team has mostly figured out where to put what generally:
- Reference documentation (including examples): in the source as far as possible, rendered in reference manuals
- Contribution guides: in-tree, close to the source
- Design documentation: in the source
- User guides: nix.dev
- Tutorials: nix.dev
There are still not enough places where the principle and rationale is written down or linked to help contributors figure it out by themselves. It's made worse that all of that is still implemented only to a small degree, making it almost impossible to infer from context whether something fits in. Also we sometimes seem to be struggling with determining what's what for a given PR, which probably cannot be solved by writing more things down because it very much depends on the situation.