Parting from the documentation team

Hi everyone,

Back in the summer of 2022 we formed a documentation team with a focus on flattening the learning curve.

We’ve worked together with Valentin to add a comprehensive tutorial on Nix language and made a number of improvements.

Today I’m parting from this project as I longer believe there are any intentions to collaborate from the documentation lead Luc Perkins.

We were discussing and putting efforts into rewriting to be flakes-first, which has stopped once Luc became the documentation lead. Besides asking multiple times for flakes stabilization timeline, there were many setbacks on the way to continue this effort.

His contributions were adding himself as the codeowner and removing starter templates in the last half a year, which has given me indications that things aren’t going in the right direction, so I wasn’t attending the documentation meetings in the last months.

Yesterday I’ve seen that completely new flakes-first documentation site has been launched without communicating a single word this is in the works with documentation team, I have lost my trust and I’m no longer willing to be involved with such ethics.

I’m sad and disappointed, I hope to restart documentation efforts in a different setting in the future.



Hi Domen,

I’m sorry to hear that. I always thought that your effort to turn - in which you’ve invested a lot of your time - into a community resource was admirable.

Apparently the same can not be said for some others. (It seems that they’ve created their own set of templates elsewhere before proposing to remove the one?)

I understand your disappointment, but I assure you that it will pass. still is a great resource and I see no reason why the (honest) community would turn its back on it.

With the important things said, and considering that this is now public, it would seem appropriate to at least ask @lucperkins to share his perspective. It seems that he has a lot of explaining to do, if possible.


sad to hear, i always loved your interaction with the community and your talks I have listened to.
i hope the setting will change in the future and we have you back with your effort in better documentations

1 Like

I’m new here and I must say it sounds a bit dishonest, if the person elected as Nixos documentation lead starts building an alternative documentation site in the capacity of “we at Determinate Systems…”, rather than contributing to common effort.


I was shocked to see the announcement of the new site and hope that it isn’t the serious failure of communication that it seems to be. Thanks for starting the conversation @domenkozar


Hi Domen,

I fully understand your intention to leave, it should feel really upsetting when things like that happen. I wonder what was the reason to keep this work in secret though, to me it looks like it would be absolutely appropriate thing to do if it were announced initially.

Hi Domen,

To start with: The work you’ve put into, Nix documentation, and the greater project has been an amazing boon to the project and its users. Thank you.

I’m going to write about two things here: Luc’s involvement, and background on Determinate Systems’ Zero to Nix project. Let’s start with Luc.

Luc works for me at DetSys. Luc worked on Zero to Nix because I told him to, because he works for me. He didn’t talk about his work on Zero to Nix because I told him not to: like a lot of project development, some of it happens in private before becoming public.

His involvement as a team lead on the NixOS Documentation Team started by being asked to serve at NixCon as someone who could get paid to do it, and I told him it was a great idea and that he should absolutely do that. My understanding was the role was primarily administrative, but I guess that isn’t the intent. He balanced his efforts between the two the best he knew how, but he was in that situation because I put him there. If this created a conflict of interest between the two, that is my fault. Don’t take it out on him. If you want to be upset with someone, I’m your guy.

Before we talk about Zero to Nix:

  • My agenda and mission (and therefore Determinate Systems’ mission) is to get more people using Nix and build a sustainable business helping people use it. I think this is similar to yours.
  • As a company, our perspective is that Nix is incredibly useful, but that the most effective way to learn and be productive with Nix is to start with Flakes. This is obviously in contradiction with the perspective that lots of people in the community have: that flakes are experimental and need serious redesign. That is fine, it is okay to believe that! But I don’t believe that, and that is okay, too.

About Zero to Nix. We set out to solve a problem: where should a person brand new to Nix go? There are lots of possible answers to this, but the answer isn’t so clear given our strong perspective on flakes. I was tired of not having a great answer to the question. With a team of skilled Nix developers and a couple of great writers, we got to work speccing out what we wanted. This is what we settled on:

  1. A learning experience which is “on rails”: with a step 1, 2, 3, … until you’re done.
  2. Very specific advice and recommendations without a lot of waffling or talking about alternative ways to do things. Nix has a lot of variety of tools, approaches, and processes, and we wanted to decisively choose some for our project.
  3. A library of “concept” documents that laid out deeper background across all the work. These fill in where people are curious, without making the main “on rails” experience too long or verbose.
  4. A lot of cross-referencing between pages in our resource, but also references to the very many external sources that also do a great job of filling out the picture.

This is a thing that didn’t really exist at the time, and we had a vision of what it could be. We looked at a few possibilities, but ultimately decided to go on our own: my belief was that presenting a strongly and exclusively pro-Flake message would not be acceptable for an upstream, official source. Having the goal of very specific advice also makes it very hard to “retrofit” it into an existing and established resource.

Why did we do it in secret? It’s fun and exciting to make a splash! It’s exciting to get your hands dirty on a new project and see if you like where you get. It’s also nice to play in a sandbox in case it doesn’t turn out right and you don’t want to continue.

If it turns out that what we wrote hits the proverbial nail on the head and is the perspective of the overall community, that is fantastic: let’s stabilize flakes and we’ll contribute it upstream.

I think we have some fresh ideas and fresh perspective that we want to tell the world about. I also think it is okay for us to do that, and that there is plenty of space for multiple perspectives to thrive.


Edited to remove an unintentional political reference.


Regardless of this unfortunate fact, your project seems to have been a success from the discussions from around the web: people interested in Nix but with no experience like it.

I just want to say one thing, meaning no offense or harm to anyone (really).
With this site there are at least three different sources of documentation outside the manual, all with a somewhat unclear relation to the NixOS project: I think this is a problem because it’s becoming confusing.

For zero-to-nix, a new user could probably mistake “from Determinate Systems” to mean from the authors of Nix. Also the quick start guide that suggest to pipe code from an unofficial url makes me feel very uneasy (I now it says it’s opinionated and there’s a box below, but it can’t help but feel like this way)

Compared to a project like Guix where there’s a single tool, website, repository and manual, Nix feels much less coordinated. I’d love if we could work to improve this.


Hi Graham,

Thank you for the documentation contribution. I know the resource will be helpful for me - and I appreciate the effort and intent that went into the product.

You do mention the site being developed as a project. I personally think you should have allowed stakeholder engagement and communication to happen, especially with Domen, who I see as a key stakeholder in the community - and NixOS documentation efforts.

Keeping things open and transparent where possible is often a good path to follow in open-source projects.

Thank you from someone who is yet to contribute - but definitely would like to at some point.


1 Like

Context from Wikipedia for those who may not have picked up on the reference:

The Hundred Flowers Movement was a period during which the CCP encouraged citizens to openly express their opinions of the Communist Party. Chairman Mao Zedong conducted an ideological crackdown on those who criticized the party.

The name of the movement originated in a poem: Let a hundred flowers bloom; let a hundred schools of thought contend.


That’s because it is.

I don’t understand this in light of the ongoing work on flake-centric rewriting of Domen pointed to. Why go with beliefs instead of discussion?

Not very fun to alienate contributors.


Conflict of interests are increasingly looming everywhere in the Nix Community, if people have noticed.

I expect more of these to come and we’ll learn how to deal with it.

Success depends on the ethics of a few, though.


That’s not how it works. Flakes will be stabilized, but not by just dropping the flag. We’ve had productive discussions about this topic in the Nix team recently and I’m not going to let this drama get in the way of that. We will stabilize Flakes step by step, starting with the core abstraction. This will be a new RFC, with a sensible scope this time, to be followed up with further RFCs.

We need to take the community’s feedback seriously.


I know, right? I never contributed to Nix Documentation, or any major contribution to Nix ecosystem (just minor nixpkgs stuff, and have been interacting with community for some years). My opinion: NixOS Foundation needs processes in place to deal with conflict of interests, and [mis]communication, [mis]understandings… There should be a clear separation between community/foundation/nonprofit and third-party/companies/for-profit interests. There needs to be more organized transparency. People can see the issues when processes for dealing with that are not in place.

Besides, I would like to ask for more information on what the NixOS Foundation/Stichting owns, controls? What about Nix/Nixpkgs/NixOS · GitHub and the projects/repositories on it?

As already mentioned, maybe the Nix community could learn with GNU Guix?

PS/Edit: I like to assume good faith. We need to be kind and see things through a processes lens to improve them. It seems important to consider sustainability issues in a genuine and transparent way. For the NixOS foundation/community AFAIK has been surviving on volunteers work, OpenCollective, companies sponsorship, …


Conflicts of interests are really hard. The tricky thing: everything usually starts in good faith and degrades slowly and un-noticeably over time and ongoing practice.

That’s why I think you’re absolutely right in demanding processes and guardrails. They are help.


No. Maybe it’s more that it now more often takes shape that is easy to describe as a standard conflict of interest, but conflict of interest has been and issue for a long time around the project. Conflict between different usage models of Nix/Nixpkgs matters no less than organisation names attached (and this is why flakes need so much negotiations, because many models don’t really need them but do suffer from the limitations of flakes, and some stuff has been made flakes-only without too much of a reason).

By the way, for similar reason, some Guix use cases rely on two repositories under different organisational control just to get a bootable system (and this is more frequent than with Nixpkgs).

Hi Domen,

thanks for all your work. Hopefully you will get over this.

Hi Graham,

maybe it’s hindsight bias, but didn’t it occur to you both, that someone being part of the documentation team and working in secret at a large documentation effort with similar topics other members of the
documentation teams would like to address, might not go down well? looks like a great resource at first glance. It just would have been great to avoid any drama.

edited to add remark about


I think you mean some hardware requires that.

1 Like
Hosted by Flying Circus.