Parting from the documentation team

Development Documentation
#16

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, …

9 Likes
#17

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.

8 Likes
#18

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).

1 Like
#19

Hi Domen,

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

#20

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?

zero-to-nix.com looks like a great resource at first glance. It just would have been great to avoid any drama.

edited to add remark about zero-to-nix.com

11 Likes
#21

I think you mean some hardware requires that.

1 Like
#22

hey guys!
just my two cents: there has already been a place to put unofficial, “not manual-ready” documentation: the wiki. next time, publishing works such as 0-2-nix there could help dramas like this.

5 Likes
#23

Not exactly, as I think some Nvidia cards should be usable as-is with Nouveau but you need unfree parts if you want CUDA.

(Of course the same third-party repository contains things like compcert, but at least these are not needed for boot)

1 Like
#24

While there’s understandably an inter-personal/emotional layer to this, that one can only be solved by the people involved - hope you’ll find away to continue your awesome work on nix documentation! :100:

But as @yuu and @blaggacao mention, I also believe that general processes for situations like this could be improved or at least be more transparent. Is there a good overview regarding current structures and responsibilities?

In my current understanding, those processes are mostly(?) defined by the RFCs in GitHub - NixOS/rfcs: The Nix community RFCs and define i.e. that release managers are appointed by their predecessors. But there seems to be no RFC about the documentation team yet?

Maybe its out of scope due to the documentation team mostly(?) working in the nix.dev repo after @domenkozar donated that to the community? On the other hand there’s nix.dev/maintainers at master · NixOS/nix.dev · GitHub which I think is great in how it transparently states goals, responsibilities, team members & their affiliations! :two_hearts:

One question which remains open for me after reading: the maintainers list says @lucperkins will be lead until 2023-01-31, so that’s just one week left - is it already clear who’s going to be the next team lead or how that process will work?

3 Likes
#25

Even though “tooling is the answer” is often a problem’s death sentence, I realized that my small recount of an independently useful tool is of odd relevance.

So I cross-reference it here for your all appreciation and scrutiny:

At the same time, by no means do I intent to trigger a tooling discussion.

#26

This post makes me sad. I had high hopes when the docs team formed last nixconf. It was a motivation boost.

Upon seeing the news about zero to nix being introduced the first thought was “another one”? Seeing the focus being on flakes I got why it was introduced. Now reading @domenkozar’s post here i realized it was introduced as part of the Nix docs team. That is surprising to me as i have a strong feeling that one of the problems of Nix is its scattered-ness.

Looking just at the documentation there is a separation of flakes vs non flakes, new cli vs old cli, 3 separate manuals, wiki, nix.dev and now zero-to-nix.

From my perspective it seems that, since the Nix docs lead and Nix cli lead are not yet aligned on using flakes or not, that a new website is needed for the Nix docs lead/team to work on.

I get the motivation to start a new website from scratch. It avoids the discussions and gets you going on your own vision (which can be really good for the community). I have felt a need to do so as well, as getting something substantial merged into the manual is currently a lot of effort.

That said, I was hoping the docs team would make sure the main Nix website and its docs are aligned and up-to-date, but now it feels more scattered than what it used to be. Where should I contribute to the docs nowadays?

Having the docs team only add docs ‘with a splash’ doesn’t make sense for an oss project with many many potential contributors. I get why @domenkozar made this post.

What is the plan for the future?

10 Likes
#27

That’s not right: Zero-to-Nix was introduced entirely independent of the docs team. Neither me or any other member of the docs team (other than Luc) had any knowledge of Zero-to-Nix being worked on before the accouncement post this week.

It’s very ironic, because in the team we talked to so many other people that worked on their own independent docs, trying to convince them to instead work on the official docs together…

21 Likes
#28

Sorry, I see now that isn’t the right way to word it. I was thinking that the docs lead with others from Determinate Systems releasing a new docs website from scratch makes it seem like a docs team effort, but it is not.

That sounds like the direction to reduce scattered-ness :+1:

1 Like
#29

I can confirm @Infinisil and @fricklerhandwerk have been reminding me a few times that I should contribute to upstream documentation and nix.dev instead of publishing my own piece of documentation on my blog, and I followed their advice, it was more work but in the end it’s upstream now and everyone benefits from it :+1:t3:

I’m thankful to the documentation team for that, because not only they suggested me to do something more useful than what I originally planned, but they offered me help to get started with the upstream documentation, where to make changes etc… :purple_heart:

33 Likes
#30

With regard to open-source development, this feels like the difference between launching a project at version 1.0 vs opening up a repo to contributions+review at version 0.0.1.

Both approaches seem valid, perhaps one is more immediately useful but the other one seems more “open”.

In any case, fully open development or not, it seems clear there was some development-level meta-confusion introduced by an official team that may have been operating to remove some product-level confusion. (and also implicitly vote more strongly than a +1 on an ongoing/WIP product-level change, flakes)

1 Like
#31

Thank you very much documentation team. Your work helped me a lot. When I was at NixCon in Paris, somebody told me that there is a new section about Nix language on nix.dev, I sat down somewhere on the side of the road, sometime around the midnight, and couldn’t stop reading until the end. And I new that things are going in the right direction. Whole conference was extremely encouraging.

I immediately read Zero-to-Nix docs when it was announced and I think it is very good as well. But have very mixed feeling from further fragmentation of Nix documentation. My opinion is that it should be merged in to official docs at some stage, otherwise it will be problematic in longer term.

I very much hope that you guys already discussed this in private. Everybody does different kinds of mistakes. Big respect to all of you anyway.

7 Likes
#32

Wow. I’m new to the party, so I’m only imagining my own capacity for mistakes or failing to see how my actions will affect others. I’m not sure I fully understand what happened. I am only beginning to understand the differences between processes in this org and in the private sector.

What is more important to me is to capture what we can learn about this situation, and see if we can develop any prophylactic action items to avoid this kind of thing in the future.

It is always easier to make something new. Some of that is due to the friction of working with others, but a lot of it in this case is incidental. When users keep using your thing wrong, it is time to ask the question, “Is my thing wrong?” When users keep opening pull requests for docs on the wrong repo, and it’s harder than it should be, because of documents in .tt files, and html fragments in sed expressions, and markdown, but you have to check in docbook xml too… to me that is intractable. I want to say, “She’s dead Jim. Time to start over.”

You could offer an AirBnB React developer more money to work in this Developer Experience, and they probably wouldn’t take it. The experience itself is alienating to the people who can fix it.

So I completely understand wanting to work outside the big tent. Sure, everyone’s peeing out instead of peeing in, but there are a lot of differences. I wonder how much harmony can be achieved if we put our minds to it.

I think there was some conflict of interest, but there is also a responsibility on the community to ask how it is incentivizing such things. People are programmed to seek pleasure and escape pain. Empathy for the human animal demands we do something about it.

6 Likes
#33

:dart:

:heart: on the entire opinion is not expressive enough. So we needed a :dart: and are also over 20 chars, now.

1 Like
#34

I’m really sad about what’s been happening, and have been in touch with everyone involved.

In the meantime, the documentation team will continue operating. Antithesis graciously offered to sponsor some time for me to work on the team in order to find a successor and keep the show running.

I wish that we all continue talking to each other.

25 Likes
#35

I wish that we all continue talking to each other.

This is a painful thread to return to, because it is about some serious misgivings and strong, hurt feelings among people who have contributed generously and prolifically to the Nix ecosystem and community. Most possible responses feel inappropriate to me. But I do want to echo this thought.

Even if it goes beyond what anyone is ‘owed’, I think it would be a gift to the community for those who feel hurt, betrayed, or insulted by these events to do what they can to keep those lines of communication open for the long term.

I am grateful for the uncomfortable work that this thread started in trying to keep the documentation team’s operation fair, open, and productive. I am likewise grateful for ongoing efforts to continue communication between contributors whenever doing so is reasonable and safe, especially at times like this when it may feel like a bit of a sacrifice. Thank you.

7 Likes
Hosted by Flying Circus.