# Dawn contributing to Nix Modules documentation
**URL:** https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685
**Category:** Documentation
**Created:** [June 27, 2023, 10:32am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685 "2023-06-27T10:32:57Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 10:32am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/1 "2023-06-27T10:32:57Z")
I’m going to begin figuring out what it is I can do to contribute to the documentation of what is apparently termed Nix Modules.
I will treat this post like a diary on the matter. But public. The verbosity might make it unappealing to anyone but me.
If you happen to be reading this for some reason and feel like contributing a little tip here and there — I would appreciate it.
Otherwise, don’t let me waste your time.
My next task seems to be: read the [Documentation Team meeting notes](https://discourse.nixos.org/search?q=documentation%20team%20meeting%20notes%20%23%20%23dev%3Adocumentation%20in%3Atitle%20order%3Alatest_topic) from the past 1–2 months. Onward.
* * *
Unfinished business:
- [feedback: they shouldn’t be named Nix Modules](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/6)
---
### Author:  [@NobbZ](https://discourse.nixos.org/u/NobbZ)
#### Post date: [June 27, 2023, 10:36am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/3 "2023-06-27T10:36:15Z")
> [@mightyiam](#):
>
> Nix Modules
Never heard of those… Do you mind elaborating on what this seemingly coined term refers to?
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 10:38am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/4 "2023-06-27T10:38:11Z")
> [@NobbZ](#):
>
> Never heard of those… Do you mind elaborating on what this seemingly coined term refers to?
I understood that they are the module system that we may be familiar with from NixOS. I suppose that’s the `imports` attribute.
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 10:40am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/5 "2023-06-27T10:40:22Z")
Checklist:
1. [2023-04-27 Documentation team meeting notes #44](https://discourse.nixos.org/t/2023-04-27-documentation-team-meeting-notes-44/27694)
2. [2023-05-04 Documentation team meeting notes #45](https://discourse.nixos.org/t/2023-05-04-documentation-team-meeting-notes-45/27874)
3. [2023-05-08 Documentation team meeting notes #46](https://discourse.nixos.org/t/2023-05-08-documentation-team-meeting-notes-46/27965)
4. [2023-05-11 Documentation team meeting notes #47](https://discourse.nixos.org/t/2023-05-11-documentation-team-meeting-notes-47/28082)
5. [2023-05-15 Documentation team meeting notes #48](https://discourse.nixos.org/t/2023-05-15-documentation-team-meeting-notes-48/28221)
6. [2023-05-18 Documentation team meeting notes #49](https://discourse.nixos.org/t/2023-05-18-documentation-team-meeting-notes-49/28281)
7. [2023-05-25 Documentation team meeting notes #50](https://discourse.nixos.org/t/2023-05-25-documentation-team-meeting-notes-50/28459)
8. [2023-06-01 Documentation team meeting notes #51](https://discourse.nixos.org/t/2023-06-01-documentation-team-meeting-notes-51/28635)
9. [2023-06-05 Documentation team meeting notes #52](https://discourse.nixos.org/t/2023-06-05-documentation-team-meeting-notes-52/28937)
10. [2023-06-08 Documentation team meeting notes #53](https://discourse.nixos.org/t/2023-06-08-documentation-team-meeting-notes-53/28938)
11. [2023-06-12 Documentation team meeting notes #54](https://discourse.nixos.org/t/2023-06-12-documentation-team-meeting-notes-54/29050)
12. [2023-06-15 Documentation team meeting notes #55](https://discourse.nixos.org/t/2023-06-15-documentation-team-meeting-notes-55/29161)
13. [2023-06-19 Documentation team meeting notes #56](https://discourse.nixos.org/t/2023-06-19-documentation-team-meeting-notes-56/29339)
14. [2023-06-22 Documentation team meeting notes #57](https://discourse.nixos.org/t/2023-06-22-documentation-team-meeting-notes-57/29500)
15. [2023-06-26 Documentation team meeting notes #58](https://discourse.nixos.org/t/2023-06-26-documentation-team-meeting-notes-58/29666)
---
### Author:  [@NobbZ](https://discourse.nixos.org/u/NobbZ)
#### Post date: [June 27, 2023, 10:43am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/6 "2023-06-27T10:43:08Z")
Indeed all references to that I am aware of talk about it at the “nix_OS_ module system”, rather than “nix module system”.
This is where my confusion stems from.
I agree that coining a new term that finds its way into official glossaries and doesn’t imply dependency to NixOS would be a good thing.
Though “nix modules” might be sound to much as if there was some native support for them in nix itself, while “nixpkgs modules” again would feel weird, as nixpkgs itself doesn’t use them at all (but in fact provides them as part of its “stdlib”).
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 10:56am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/7 "2023-06-27T10:56:23Z")
Would it make more sense that what was suggested that I contribute to is not whatever is behind the `imports` attribute and instead it is whatever abstracts NixOS modules? Or perhaps are these two parts of the same mechanism?
---
### Author:  [@Infinisil](https://discourse.nixos.org/u/Infinisil)
#### Post date: [June 27, 2023, 10:57am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/8 "2023-06-27T10:57:17Z")
Generally it’s called the “module system”. It’s not tied to any packages from Nixpkgs nor tied to NixOS
Currently @roberth and me are maintaining it
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 10:59am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/9 "2023-06-27T10:59:22Z")
Brilliant. Thank you for chiming in. I don’t know what to ask you yet.
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 11:12am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/10 "2023-06-27T11:12:27Z")
First mention of module system in documentation team meetings says regarding NixOS Manual:
> Very minimal module system docs are in here, probably shouldn’t even be in the NixOS manual, since it’s not specific to NixOS
And mentions this PR: [Module system documentation refactor by spacekookie · Pull Request #526 · NixOS/nix.dev · GitHub](https://github.com/NixOS/nix.dev/pull/526)
And that’s it. I used text search for `module` in all of those notes and found only those items.
So, let’s take a look at that PR…
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 11:16am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/11 "2023-06-27T11:16:21Z")
Before that, current thoughts:
1. The Nix module system (or whatever it is called) should be documented somewhere canonical. Canonically.
2. There should be mention of it and how NixOS uses it in the NixOS manual.
So, I’d be interested in seeing:
1. What documentation currently exists for the Nix module system, whether it is in the NixOS manual or in a canonical location of its own or elsewhere.
2. What documentation exists for how NixOS uses this module system in its manual.
A desired vs. existent check, I suppose.
---
### Author:  [@roberth](https://discourse.nixos.org/u/roberth)
#### Post date: [June 27, 2023, 11:28am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/12 "2023-06-27T11:28:19Z")
I’ve recently got involved with the docs team, and I think the module system is an area where I could be particularly helpful.
Indeed the goal would be to have good documentation for it as a standalone project independent of NixOS. (Although an occasional reference would be ok, these must not be required for understanding)
What documentation currently exists for the Nix module system
It’s split between
- Nixpkgs manual (only since recently, very incomplete, just `evalModules` reference documentation)
- NixOS (fairly NixOS focused, but some parts can be moved over without much editing)
- Code and code comments. The manuals are arguably incomplete, and the code contains some user facing info.
The latter should of be mostly replaced by URLs and references to .md files.
What should remain of the docs in the NixOS manual is probably not a lot, because we want to move non-reference (and non-explanation?) docs out of the manual, into nix.dev.
I don’t think it’s an easy task to pick up, but if you have the time we can come up with a plan. I think it’d be crucial to work out the concepts and types first, so that the reference documentation will be consistent, and we’ll have a good foundation for further docs.
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 27, 2023, 11:39am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/13 "2023-06-27T11:39:07Z")
Thank you for summarizing. I have a few hours per day during this and the next two weeks. Then, Summer of Nix begins, which may decrease this to one hour a day for that duration. Possibly adding some more during weekends.
Does that sound alright? I’d love your help figuring out a plan, as much as you’d be willing to.
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 29, 2023, 5:51am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/14 "2023-06-29T05:51:58Z")
Alright. Discovering the Nix module system existing documentation. So, where is the repository?
One part of it seems like the options system, which seems to live [here](https://github.com/NixOS/nixpkgs/blob/2fdcb339cd3672cb522af3eba54e2a1e5d3362ac/lib/options.nix).
This seems to be currently documented in the source code. So I suppose that that’s the source of truth. So, ideally, we’d consume that truth and produce documentation. Auto-generated Nix documentation is not a new idea. I wonder what it would take to implement. And I wonder what progress has been made towards it.
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 29, 2023, 5:56am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/15 "2023-06-29T05:56:56Z")
The other part of the Nix module system seems to live [here](https://github.com/NixOS/nixpkgs/blob/2fdcb339cd3672cb522af3eba54e2a1e5d3362ac/lib/modules.nix).
The same applies. Reference documentation could be generated from source. It should be, I suppose.
Since I’m not going to solve this problem in this context, I suppose we could see the source as reference documentation, instead of copy-pasting into some documentation. I don’t like duplication of truths. It carries high risk of de-sync between source and copy.
So, if I’m not to produce reference documentation, I should take a look at the higher level documentation.
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 29, 2023, 6:20am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/16 "2023-06-29T06:20:28Z")
Would it make sense to begin documenting the Nix module system in nix.dev ?
---
### Author:  [@fricklerhandwerk](https://discourse.nixos.org/u/fricklerhandwerk)
#### Post date: [June 29, 2023, 6:45am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/17 "2023-06-29T06:45:00Z")
Yes, as you say anything but reference should go to nix.dev. But we could also have a design document in Nixpkgs right next to the code and import it into the manual, to help readers navigate and understand the code.
Exporting doc comments sensibly probably requires a refactoring given how `nixdoc` currently works.
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [June 29, 2023, 10:58am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/18 "2023-06-29T10:58:43Z")
If I was to move, with appropriate modification (which I don’t know yet) [Writing NixOS Modules](https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules) from the NixOS manual to nix.dev, would the NixOS manual be worse off in any significant way? Would it lack something important about modules?
---
### Author:  [@fricklerhandwerk](https://discourse.nixos.org/u/fricklerhandwerk)
#### Post date: [June 29, 2023, 11:34am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/19 "2023-06-29T11:34:58Z")
We should not just move around large chunks of documentation, but rather go very carefully and try to understand what’s wrong with a given piece and improve it incrementally in place. I recommend starting with obvious changes such as completing and structuring parameter listings. The scalable approach to that is documenting library functions in the code and collaborating with @pennae and @sternenseemann on figuring out how to sensibly develop `nixdoc` to make best use of in-code documentation.
What also works but takes more time to produce results is improving the conceptual introductions to get them right. While the module system is a generic mechanism, that chapter is highly specific to NixOS. We should instead start documenting the mechanism separately, for example on the Nixpkgs manual. Exposing the library there in more detail would be a good way to do that. I remember @roberth had a pull request in that direction.
---
### Author:  [@blaggacao](https://discourse.nixos.org/u/blaggacao)
#### Post date: [June 29, 2023, 1:23pm UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/20 "2023-06-29T13:23:40Z")
The Nix Community’s module system is a type system with docstrings and a lattice value priority resolver \*.
Form first principles, I found one paragraph of lattice theory e.g. from wikipedia extremely helpful.
I noticed that this is at the core of the module system when studying the `cue`-lang documentation. 😄
\* sort of every configuration management system _is_ in better or worse ways. Nix Community’s solution is one of the better ones, which has been the trampoline in which `nickel` happened.
And what would this discussion contribution be without a [shameless, but imo helpful, contextual plug](https://std.divnix.com/explain/why-nix.html)… 🥷
---
### Author:  [@mightyiam](https://discourse.nixos.org/u/mightyiam)
#### Post date: [July 2, 2023, 5:41am UTC](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685/21 "2023-07-02T05:41:39Z")
With regard to making the best use of in-code documentation, does anyone here feel that [https://github.com/NixOS/rfcs/pull/145](https://github.com/NixOS/rfcs/pull/145) is going towards being a solution for that?
[Next page](https://discourse.nixos.org/t/dawn-contributing-to-nix-modules-documentation/29685.md?page=2)