This Month in Nix Docs - #2 - April 2023

Development Documentation
1

This Month in Nix Docs - #2 - April 2023

This edition is a little late since last week I prepared to move to a new city 1300 miles away. As you can imagine that takes up a lot of time, but I’m back to Nix-ing and ready to present another month of progress on Nix documentation!

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!

Google Season of Docs and Fundraising

Last month we submitted our application to Google Season of Docs with the hope that the funding would help us hire a paid editorial lead and a Nix expert that would help us develop a curriculum for how to most effectively onboard new Nix users. Unfortunately we were not chosen for Google Season of Docs. However, soon after we found out we were not chosen for Season of Docs, a fundraising effort was announced to try to raise the money that we applied for (full disclosure: this post is by @ron, my future boss at Flox, starting next week).

To date we’ve received >$17k, which is amazing! You can follow along with the progress or donate to the fundraising effort on OpenCollective.

With this money we’re looking to hire a few paid contributors for this project. If you know someone that’s an excellent teacher or has experience developing curricula, please direct them to the job description page!

Projects

Documentation rendering infrastructure

One of the tricky aspects of Nix documentation is that different projects have their own way of generating their documentation. For instance, the Nix Reference Manual is rendered with mdbook, the NixOS Manual is rendered using nixos-render-docs, and Nixpkgs uses this rendering pipeline:

  • Nixpkgs lib functions scraped to Markdown via nixdoc

  • Markdown to DocBook XML via pandoc and nixos-render-docs

  • DocBook XML rendered to HTML via DocBook

Contributors @pennae and @asymmetric have been making progress on the rendering infrastructure to allow for more consistent rendering tooling across projects.

Replacing DocBook with Nixpkgs-flavored CommonMark necessitated writing our own rendering infrastructure (nixos-render-docs)—no renderers existed that easily supported the entire feature set of Nixpkgs markdown, and while Pandoc came close it still used DocBook in the background to render to HTML and other targets. nixos-render-docs is capable of rendering most of the Nixpkgs manual by itself, but still missing are output to ePub (which is needed for both the NixOS and the Nixpkgs manual) and many minor tweaks to nixos-render-docs for features used in the Nixpkgs manual that aren’t used by NixOS. Help with these, especially the ePub export, is very much welcome. If you actually use this ePub output format we’d like to hear from you.

Learning Journey Working Group

The project I’m leading over at the Learning Journey WG is trying to figure out how exactly to teach Nix to a new user. I’m really happy with the discussions we’re having over there, and I would love it if you, dear reader, would join us. Your experience and how you learned Nix is valuable input for how we’re developing this curriculum.

The current idea is that we’ll have the user create a web server in Python that sits behind a proxy (e.g. Nginx) and talks to a database (e.g. Postgres). This will allow us to touch on a variety of topics such as:

  • Dropping into an ephemeral shell environment with nix-shell -p.

  • Setting up a development shell with shell.nix

  • Building a Python application in which the dependencies are specified with Nix

  • Running integration tests with NixOS VM tests

  • This puts the user in contact with NixOS configurations, the module system, etc

We haven’t actually written anything just yet, but it’s super important to understand the problem you’re working on before you jump into implementing anything. In the case of designing a curriculum the “problem” is answering questions like:

  • What is the correct sequence in which to introduce certain topics?

  • What is the correct “chunk size” in which to introduce new topics?

  • Nix can do all kinds of awesome, impressive stuff. How do we show that without introducing scope creep?

  • Do we keep the user on the happy path to reduce friction while learning something unfamiliar, or do we show them the hard stuff that they’re going to inevitably run into at some point?

  • Who is the audience we’re talking to? Is it Linux enthusiasts coming to Nix via NixOS? Is it people interested in reproducible builds? Is it people interested in bootstrapping development environments? How do we choose topics/paths that speak to all of these use cases?

These kinds of questions are why we’re looking to hire an expert teacher. I myself have multiple teaching awards from teaching during my physics PhD, but I’m far from what I would consider an expert. In the next month we’ll start sequencing and chunking this user journey so that we can identify how many steps the tutorial will be, in what order they’ll exist in, etc. As part of this process we’ll also be identifying where existing documentation has gaps for new users.

Documentation PRs Merged

NixOS/nix

NixOS/nix-pills

NixOS/nix.dev

9 Likes