This Month in Nix Docs - #3 - May/June 2023

Development Documentation
1

This edition is double-stuffed because for no good reason I completely forgot to make this post last month! I now have a repeating calendar event to remind me to make these. There’s a lot that’s been going on, so let’s dive in!

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!

Projects

Rendering infrastructure: the great de-docbook-ification

In the previous edition I detailed progress removing docbook from the rendering pipeline.

To recap, docbook is an XML-based authoring and rendering tool that has historically been used to render the NixOS and Nixpkgs Manuals.

For the past two years there have been efforts to remove docbook from the NixOS and Nixpkgs Manuals.

With Nixpkgs#239696 (which is the first time I’ve ever seen a 6-digit issue number), the final bit of removing docbook from the rendering and authoring pipeline will be complete. While this PR is not yet merged, the outlook is good. Huge thank you to @pennae for their work on this, it has been a long time coming.

This work is a big deal because once this PR is merged it unlocks some much-needed improvements to the documentation. For instance, splitting the manuals up into separate pages rather than a single large web-page would become possible.

That helps with SEO and discoverability.

Learning Journey Working Group

Over the last two months the Learning Journey WG onboarded our Editorial Lead, which was made possible by everyone’s generous donations to the OpenCollective campaign. Unfortunately, our Editorial Lead later had to step back from the role for health reasons.

In their short time with us, they made some great observations and provided some very useful feedback that we’ve incorporated into a better structured working process.

The idea is that we have what is essentially a month-long sprint process that produces tutorial outlines that are sufficiently detailed enough that contributors can pick them up and start writing. With so few people in the WG, there’s no way we can decide on what content should exist while also writing said content.

We have a tracking issue covering which tutorials we’d like to see and their progress. Note that we don’t consider a tutorial “done” unless the full tutorial is available on nix.dev, so it may look like there’s no progress from that tracking issue even though there are outlines in progress, etc. See the specific issues it links to for details on individual tutorials.

This is what the process looks like:

  • Week 1: Decide on which tutorials we’d like to create outlines for, and solicit feedback from the community.
    • This is based on which topics we’ve already created outlines for, which prerequisite topics we’ve already covered, etc.
    • Regarding soliciting feedback, I did our first iteration of that here. We received precisely zero feedback, and I’ll gladly take the blame for that given that I posted it in the “Development” category rather than something like “Help” or “Announcements”.
  • Week 2: Incorporate feedback, decide on which specific activites the tutorials will cover.
    • The intention for getting feedback is that there’s a lot of people with a lot of Nix experience out there, and we’d like to leverage their expertise.
    • In this weekly meeting we also assign a tutorial outline to a particular contributor for them to work on asynchronously before the next meeting.
  • Week 3: Discuss blockers, do group reviews
    • This week is targeted at checking in with the tutorial outline progress
  • Week 4: Discuss blockers, do final review
    • By this time we hope that the outlines are in a good state and can be merged.

New contributors

In the last two months we’ve also added a few consistent contributors, which is great! The current documentation team is very small, so any time we have new contributors it makes a significant difference.

One area in which we’re sorely lacking is owners for various sections of the NixOS and the Nixpkgs Manuals. @alejandro has taken on the task of reworking the Python section of the Nixpkgs Manual, which currently contains a mixture of both explanation, how-to, and reference materials.

Ideally a piece of documentation would only contain a single category of documentation, so @alejandro is working to identify which content should stay in the manual and which content can be extracted out into other formats (tutorials, short recipes, etc) so that readers can quickly and easily find the type of content that they’re looking for.

@henrik-ch and @JillThornhill have been working on the Documentation Team’s documentation survey, which is a survey of both first- and third-party documentation including the Nix Pills and blog posts from around the internet. The intent is to provide a library of examples to draw inspiration from when writing new documentation.

@henrik-ch and @JillThornhill have been reading each link then adding summaries and some metadata so that contributors can easily search for links covering specific topics while also having an idea of how up-to-date the link might be.

Meeting notes

Documentation Team

Learning Journey Working Group

RFCs

Documentation PRs Merged

NixOS/nix

NixOS/nixpkgs

  • #237669 nixos-render-docs: De-lint using ruff --fix (@l0b0)

NixOS/nix-pills

NixOS/nix.dev

13 Likes