Joining the Nix Documentation team

So this happened almost 3 weeks ago: I joined the Nix documentation team. I wanted to write about this here sooner, but haven’t found the motivation to do so until now (I find it very hard to write things here because I’m mostly writing for myself).

It’s been a few months since my first commit contributing some documentation to Nixpkgs. I had a positive experience when doing that, mostly because I expected that it would take weeks until someone looked at my PR, but it actually took less than that, and the feedback I got was very decent.

The Nix/Nixpkgs/NixOS manuals and overall documentation of the Nix ecosystem have a reputation for being very poor, confusing, and lacking in many areas. I don’t remember how, but I found some details about the Nix documentation team, saw they had meetings that were open to everyone, and my curiosity got me to join one of those meetings. After all, I wanted to know why a documentation team existed while the manuals and overall documentation were in such poor state.

I got to know some people in the meetings, and kept coming back to learn more. After a while, I kinda figured out the answer to some of my questions: most of the people on the documentation team are volunteers (just like me now!) who work on their free time and mostly only on the things they particularly care about or are motivated to work on, which seems absolutely fair. To my knowledge, only two people in the team are paid to work on Nix overall, which means they have to dedicate time to not only documentation, but a lot of other things that they’re working on. And I believe they don’t get to work full-time on Nix overall, although they can dedicate a good amount of their time to it.

Moreover, I discovered that the documentation team doesn’t have a lot of tools that help them get things done, especially at the scale of something like Nixpkgs/NixOS. Given that I greatly enjoy to work on tools and make inefficient things efficient, I decided to help a bit by making the Nixpkgs manual more consistent.

At the beginning, this was supposed to have a very narrow scope, but as I started to work on it, I realised I’d need to at least understand each part of the Nixpkgs manual before I was able to make that part more consistent. And when I started reading things, I realised how out of date some things were…

So I decided to say “what the hell, why not” and start a journey to make the Nixpkgs manual more consistent AND update all the content in it. This is a ridiculously large scope, so I also decided to only update content that already existed, and not document parts that were previously undocumented.

After a while, I think the folks from the documentation team saw that I was serious about this effort, and invited me to join the team. I accepted after they told me I wouldn’t have any extra responsibilities and wouldn’t be expected to do anything extra. I’m already taking a huge amount of work here! :)

So that’s how it happened.

My plan now is to continue with my efforts, which means I have to work on some tooling to make sure that we can keep track of the “freshness” of each part in the Nixpkgs manual. This should help a lot to figure out what needs attention, and maybe in the future (once it is proven to be effective) we could even use this tool to figure out when new changes on Nixpkgs would possibly make the manuals outdated, and force people to update the documentation as well.

Obviously, there’s a lot of work involved in all of this. I’m glad I can dedicate as much time as I want to it (which means I still have time to work on my other project, which takes priority), because I’m a volunteer after all.

However, I wouldn’t mind discussing opportunities to get paid for some future work, or for this work that I’m already doing, but I’m not focusing on that right now. There are already some interesting things happening as a consequence of what I’m doing, so I’m just going along with what’s happening and seeing where that leads.