NixOS
Module system documentation refactor
See #517 for details. Still very WIP and incomplete.
I'm still thinking about the docs layout:
Currently I opt to explain the structure behind modules first, then going for "how to configure a system". My reason for this is that using modules obviously has a dependency on explaining how a module looks (at least the abbreviated version).
While the options vs config split is less relevant for understanding how to setup a NixOS system, it also doesn't hurt and doesn't currently take up too much space.
One alternative would be to swap the sections: focus on system configuration first (i.e. how to use modules) and then into how to write them (which explains the structure).
A third alternative would be an A-B-A structure, where a small TLDR section in the beginning explains the basics of what configuration is and how you vaguely use it (maybe with a link to https://search.nixos.org/options for anyone familiar enough with what they're doing), then explain how it works, and finally a more detailed section about how to configure a system.
I think I like the structure as it is now the most, but happy to hear feedback.
I also haven't read a lot of the other docs yet so I'll have to do a few passes for tone.
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2023-04-27-documentation-team-meeting-notes-44/27694/1
I think the first goal should be to get the reference documentation in order, in the Nixpkgs manual, and only then write guides and tutorials. (As I understand it, guides and tutorials are the scope for nix.dev)
The lack of good reference documentation really shows, because the first thing you had to do in this document is describe things that should be in the reference documentation instead.
When that reference documentation is available, it will be easier to write
- tutorials, which can point to the reference docs for info about the features that were used. This way your tutorial can focus on going through the motions without get stuck in details.
- guides, so that you only have to go into what needs to be done to achieve some small range of tasks.
@roberth fully agree. This collection is still enormously valuable because we now have an outline of what needs to be done with the reference documentation in order to support the beginner tutorials and guides.
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2023-06-01-documentation-team-meeting-notes-51/28635/1
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2023-06-15-documentation-team-meeting-notes-55/29161/1
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/10
We now have this new module system tutorial. Other than that it would be best to focus on improving the NixOS reference docs as mentioned above, which already contains a lot of the same content as mentioned here. Furthermore we have a small initial Module system reference docs that could use a lot of love.
I'll close this for now, let me know if you'd still like to continue working on this
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2024-03-07-documentation-team-meeting-notes-112/40963/1