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! 
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! 
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…
21 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 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 
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… 
33 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
on the entire opinion is not expressive enough. So we needed a 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