Module system documentation refactor #526
Conversation
| - https://www.youtube.com/watch?v=cZjOzOHb2ow&t=117s | ||
| - https://github.com/tweag/summer-of-nix-modules | ||
|
|
||
| # NixOS modules |
There was a problem hiding this comment.
I think this tutorial should not be specific to NixOS, because the module system has a lot of other applications too. And once the module system is explained generally, it will be much easier to just explain the NixOS-specific bits on top of it.
There was a problem hiding this comment.
I'd really go for an incremental style like https://github.com/tweag/summer-of-nix-modules/commits/master (check out the commit subjects in chronological order), incrementally building up features of the module system one-by-one.
There was a problem hiding this comment.
More sources: https://wiki.nikiv.dev/operating-systems/linux/nixos
| - https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules | ||
| - https://nixos.org/manual/nixos/stable/index.html#ch-configuration | ||
| - https://nixos.wiki/wiki/NixOS_modules | ||
| - https://github.com/NixOS/nixpkgs/pull/202204 |
There was a problem hiding this comment.
Moar
|
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
|
|
@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 |
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
TLDRsection 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.