Parting from the documentation team

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

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

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 https://github.com/NixOS/nix.dev/tree/master/maintainers 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

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.

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

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…

29 Likes

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

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:

36 Likes

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

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

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

:dart:

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

1 Like

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

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

Hi Domen,

I’d like to re-state that I’m sorry you found yourself in this situation and felt you had to step down.

Our hope was that we’d all move beyond what happened here and we’d just let it slip into distant memories. Since it hasn’t, I wanted to share that I’m a bit confused about some of what you’re saying here. I think there may be some misunderstanding.

You suggested his contributions were limited to adding himself as a codeowner, and removing the starter templates. When I looked at the codeowner PR, he isn’t in there. Everything in there is setting you as the codeowner, with the exception of two lines that also include Valentin.

For the starter templates, its really a misnomer since the unmerged pull request was only removing one starter template: a link to a devenv getting-started guide. This was part of an effort the documentation team was going through to make nix.dev more of a neutral resource, and was also agreed upon by other members of the docs team.

I know for sure there were lots of discussions about making nix.dev flake-first, but the documentation team has continued to decide against it until they’re no longer experimental.

Regarding the progress stopping when Valentin’s documentation funding team ended and he stepped down, that looks like it might be simply that Valentin stopped contributing.

Looking at the data, Valentin (fricklerhandwerk) made a remarkable number of contributions:

Author Additions (Sum) Deletions (Sum) PR (Count)
fricklerhandwerk 2,764 280 26
yukiisbored 622 525 10
zupo 289 165 3
app/dependabot 220 163 19
domenkozar 206 254 2

and looking at specifically these contributors (excluding dependabot), we can see that Valentin was really carrying the project:

(where the data came from)
gh pr list --repo NixOS/nix.dev --limit 1000 --state all --json additions,author,baseRefName,body,changedFiles,closed,closedAt,comments,createdAt,deletions,isDraft,labels,mergeable,mergedAt,mergedBy,milestone,number,state,title,updatedAt,url

converted into a csv:

.[] | select(.state == "MERGED") | select(.createdAt >= "2022-01-01T00:00:00Z" and .createdAt < "2023-01-01T00:00:00Z") | select(.mergedAt >= "2022-01-01T00:00:00Z" and .mergedAt < "2023-01-01T00:00:00Z") | { number: .number, additions: .additions, deletions: .deletions, author: .author.login, createdAt: .createdAt } | [.number, .additions, .deletions, .author, .createdAt ] | @csv

There are of course many questions as to why we chose to write documentation on zero-to-nix.com instead of nix.dev. A big one is answered above: we wanted to write docs for flakes, the team didn’t want them.

But that wasn’t the only reason.

While I know the intent was to support publishing a book, I was not thrilled about aspects of nix.dev at that time:

  1. Although you had agreed to generously donate it to the Nix community, at that time it was not yet a true community project. Contributing to nix.dev required signing a CLA — a CLA that assigned complete ownership to you, Domen, personally.
  2. Although ostensibly a neutral community resource, nix.dev discussed Cachix quite a bit, a proprietary product created by you, Domen, in a variety of places (for example: Continuous Integration with GitHub Actions — nix.dev documentation), and frequently it’s mentioned in a matter-of-fact way that doesn’t make it clear that it’s a proprietary service. Several references remain to this day (which I think can be fine!)

These things made me feel uncomfortable making significant contributions on behalf of Determinate Systems. It’s your prerogative, of course, to create documentation sources that promote Cachix and Devenv. But I don’t think it’s your prerogative to do so in a community resource and to actively resist making that resource more neutral (Remove Nix starter template by lucperkins · Pull Request #404 · NixOS/nix.dev · GitHub).

To be clear, I have no objection - moral or otherwise - to people and companies building documentation sites that serve what ever purpose. I just didn’t want to contribute to this one. I’m glad the CLA is gone now, and that nix.dev is a fully community resource now.

So, there you go. I thought that might be interesting or useful context for your future documentation efforts.

13 Likes

I have censored my own reply to a comment I cannot see

I have a lot of respect for you (Domen and Graham) both for your prolific work in Nix community projects, especially in the years when I was new to Nix and was really taking everything in. It’s painful to see people who I’ve known to be generous and kind with the time, code, and personal help they donate to the community at odds with each other, or worse (effectively or formally) pushed out of Nix projects. (It’s painful even when I do feel partial to one side!)

I’ve been clumsy in the past in expressing specific hopes for personal or factional reconciliations, and sometimes just made things worse for people who were feeling alienated or betrayed. So I don’t want to say much.

But I do want to say a few things that I imagine many here feel:

It sucks to see mistrust live this long in the Nix world. I hope that, by increasing confidence in Nix’s independence and inclusivity, good community governance will soon create new room for charitable interpretations of the past and present that currently seem untenable to some. And my support for posts like this recent comment from Graham is rooted in that hope rather than any kind of factional interest or sides-taking.

5 Likes