# This Month in Nix Docs - #5 - September 2023

Development Documentation
1

Community

The Documentation Team can be found in a number of places. Check the Documentation Team page and drop in if you’d like to contribute!

NixCon

Several members of the Documentation Team met up at NixCon, and a few of us gave talks:

New Nix manual section

The Nix Reference Manual has a new section on the “import from derivation” pattern: Import from Derivation.

Reworked derivation section of Nix manual

The “Derivations” section of the Nix Reference Manual got a rework. You can see the new page here: Derivations

Projects

The Learning Journey Working Group was on hiatus for the last month while I (@zmitchell) traveled to Germany to speak at NixCon and then immediately travel to New Mexico to speak at RustConf. As you can imagine, after two weeks of back to back conferences I needed a break. The Working Group is picking back up this month.

How You Can Help

If you like what we’re doing, consider joining the documentation team or donating to the NixOS Foundation’s documentation project on Open Collective to fund ongoing maintenance and development of learning materials and other documentation.

Documentation PRs Merged

NixOS/nix

NixOS/nixpkgs

NixOS/nix-pills

  • #220 fix(typo): rename mymkDerivation to mkDerivation in Conclusion of pill 08 (@koralowiec)

NixOS/nix.dev

12 Likes
2

I really enjoy seeing all the work you are doing for the Nix ecosystem! I was wondering, would it be OK to ask for your opinion on Documenting bugs and interfaces worth improving in Nixpkgs and NixOS …

3

One more thing that landed is this PR finally adding a very minimal list of supported platforms for Nixpkgs. This should begin to answer the question: “where can I use Nixpkgs, and with which level of support?”

It is very minimal, and there’s much more work to do:

If anyone is interested in helping out, feel free to contact me or anyone in the Doc Team.

2 Likes
4

I don’t find any mention on the NixOS Wiki here. What are the plans on updating/maintaining those articles? Where should the source of truth really be?

5

The documentation team does not maintain the NixOS Wiki. Here’s some information on that. It’s a community resource running on very outdated insecure software, and the admin is unresponsive. @Mic92 keeps backups just in case.

The source of truth for any documentation should be as close to the actual code as possible. If you want to contribute something and don’t know where to put it, the document linked above should provide some general guidance. Please reach out to the documentation team for details.

With NixOS the problem is that documentation doesn’t really have maintainers and it’s not very well structured overall, so it could be tricky to merge substantial changes. The documentation team unfortunately doesn’t have the capacity to deal with that right now, and our call for maintainers is still valid.

6

Understood. There is a gap in documentation that should also cover guides in a unified way. For example, what does the documentation team goal is in terms on providing say “How to use Zsh”.

I would expect (not necessarily from the NixOS org itself but the wider ecosystem) that there should be something written somewhere that details, how to use the programs.zsh module in NixOS and Home Manager, the difference between using one and the other, and cover some common usecases. This probably isn’t the best example, but the point is that if the documentation is “as close as the code” as you mention, you lose a way to guide new comers to the wider Nix ecosystem which is not only the NixOS modules but also HM and other Nix tools that exists out in the wild (like Poetry for example).

7

That’s true, and higher level guides will have a place on nix.dev. Given limited resources, for now we have to focus on well-understood use cases, that don’t fan out too much. We’re planning an introduction to declarative configurations that should provide enough guidance for people to figure out the details themselves. But we still need some time to finish the scaffold we’ve been developing in recent months. Once it’s laid out it will be a lot easier to fill the blanks.

You can have a preview with nix-shell --run "./live"

8

This absolutely has a place on nix.dev, it’s just that no one has written it yet. If someone wants to write these and submit them here’s the process:

  • Work on a draft for no more than an hour
  • Submit a draft PR with the tutorial/guide
  • Tag me (@zmitchell) for review
  • Edit
  • Repeat
  • Merge

There’s basically two people writing tutorials specifically at the moment, me and @proofconstruction. When we say that we’re resource constrained that’s the reality of the situation. I’m also involved in a lot of other things at the moment so my output is not high. Without more people helping we’re going to be tied up in teaching Nix fundamentals for a while before we have a chance to get to specific programs/ecosystems.

9

I think the diagram is pretty accurate.

Generally I think we should document what exists today, bugs and all. I’d rather have a manual that says “here are the bugs, depend on the buggy behavior at your own risk” rather than have someone waste time because they didn’t know the bug existed. We’re all consenting adults here, if you want to depend on something guaranteed to break, that’s your problem.

The big caveat here is that someone first has to write those docs (that’s you in this case), someone has to review the contribution (which could mean multiple rounds of back and forth to even put the material in the right place), and (critically) someone has to keep an eye on it once it’s merged so that if the bug ever goes away the documentation is updated.

That all takes time, energy, etc, and the documentation team is chronically running on fumes in this regard.

I only had time to look at nixpkgs#240780 and I didn’t give it a thorough look over, but I think that particular contribution is in a gray area with regards to reference/how-to. I would personally accept in either the NixOS Manual or in the Recipes section on nix.dev as both of those resources stand today.

My personal belief is that it needs to be much easier to submit new documentation.

1 Like
10

I’d like to contribute but what I see is the nix.dev is like a manual more than a wiki. I don’t think that scales for what I was thinking of. For example having one guide per every database nixpkgs provides, every service, window managers, etc.

I mean, NixOS wiki should be the place those articles should go, but if the admin is unresponsive as you said, maybe we should create an alternative.

11

Packages and NixOS modules already have docstrings, but they usually contain very brief text and superficial examples. Again, this is simply a matter of package/module maintainers taking care of that.

Should we ever move together packages and service definitions in the pkgs/by-name directories, that would be a natural place for long-form text, extended examples, and user guides.

I may be completely off, but the main advantage Wikis have over proper version control are WYSIWYG editors, which make them slightly more convenient to work with for content creation. This has to be traded against that content drifting out of sync with the code though. Having a GUI for in-code documentation would resolve that, though I imagine it would be quite expensive to make one.

12

Doesn’t nix.dev have the same risk of drifting out of sync though?

13

Yes it does, this is why we’re focusing on very high level things. We discussed at length how one could maintain more material next to the code, but we need good guides and overviews in a visible place sooner rather than later. And the Nixpkgs manual is so badly structured and so hard to work with that it would take ages until it got to a point where we could actually start extending it. Ask @alejandrosame for first hand experience.

The goals for this year will be concluding the documentation project as originally intended (the timeline shifted for availability reasons) and synchronizing nix.dev to Nixpkgs releases to put some bounds on the drift. The next steps for afterwards are quite clear, and we’re essentially limited by available dedicated time.