I’ve recently made some changes to nixos.wiki, and was surprised that there was absolutely no review process involved, especially considering i’ve just created a brand new wiki account.
Maybe I have wrote complete nonsense, or maybe the style was not up to community guidelines - noone checked.
Is there something i’m missing? Maybe at least some wiki moderators will be informed about fresh changes and won’t let incorrect information stay up for too long?
(described changes were done here)
That’s true, the wiki is not really curated by anyone. If you want to add to official documentation, check the contribution guide on nix.dev or get in touch with the documentation team.
We have a plan, there is a lot to do, and any help is very much appreciated.
Wikis are kind of by definition user maintained with low curation/barriers of entry, that’s the whole idea. You can do similar things to wikipedia pages, where they have not been forcibly locked down for specific reasons such as political brigading and whatnot.
It’s probably also why our wiki is so poorly maintained, I have a feeling culturally NixOS users are more likely to contribute to a git repo with official documentation than add something to a wiki.
wiki covers way broader scope of problems compared to documentation (especially regarding NixOs configuration tricks)
Even taking the same example - how to set up NixOs on btrfs partition. It’s possible, it’s quite easy, but official documentation does not cover it, while such topic is important to be delivered correctly, since it affects installation process.
And yes, ofcource wiki is user maintained, but just as with wikipedia users may have some “weight”, and modifications by just joined users may be held for a review by more trusted ones.
It would be very nice actually to have wiki changes be discussed/approved the same way PRs on github are, but not sure it’s possible
That’s primarily because the contribution process to official documentation is still fairly high-friction and no one seemed to have bothered to go through the pain on that particular topic. Especially for the NixOS manual there are no dedicated maintainers who will have the time to review pull requests. @jtojnar does a great job already, but like any volunteer will be time-constrained and fighting against a flood of notifications. We’ve done a few things to make meaningful contributions easier, but it’s a long way to go. The call for documentation maintainers is still relevant.
It’s not possible. If you’re willing to go that far you may as well contribute to official docs. We’d be glad to have you around the documentation team if you want to help out!
I merely wanted to fill some gaps I myself ran into while setting up btrfs with nixos. Wiki was the most familiar thing to suggest edits to.
Surprisingly, I don’t think i even saw that official documentation page before, probably because it barely mentions topics of nixos configuration.
Judging from some randomly picked topics I see here, people do rely on wiki, it’s a valuable source of information.
I see if i can contribute to official documentation too.
Maybe migrating articles from wiki into it is a way to start?
It’s a great way to start! Just don’t be disappointed if many things will turn out orders of magnitude harder than they seem because the correct answers are barely known or really tedious to write down in a way others can make use of them. But we’ll sit through with you.
Case in point: You probably want declarative storage layout with disko instead of messing around with Btrfs manually, but getting its documentation up to speed is a rabbit whole in its own right. But it would help a lot of people to stop caring about these details once and for all.
It’s third party for the moment though, so won’t end up in “official” NixOS documentation, right?
Would be cool to have docs on this in the NixOS manual, which will likely be closer to current wiki contents. Or maybe be a bit lenient on this kind of thing and actual refer to disko from the NixOS docs, given how much nicer it is…
Discussion for PRs I s’ppose.
Docs team is on the path to make a policy decision about this.
Would be even cooler to have it as part of the NixOS installer, but someone™ will have to put in the work and maintain it. Let’s be honest about how likely that is without funding.
The main problem I see everywhere is that most of everything is half-finished because people run out of time or motivation. And I’m not talking about moonshots here. Even fixing seemingly small things – in a way that there are strictly better than before, not making them worse or perpetuating cargo cults and anti-patterns – often turns out to be a significant undertaking. Things like moving a page in a way that doesn’t break lots of links. Figuring out the right place to move to. Or whether the information on that page is even correct or relevant. Then finding root causes for such friction, and fixing those…
In the past there was an effort to get rid of the wiki and move everything into the nixpkgs/nixos documentation or into recipe repositories of actual code. This is how nixos-hardware was created. The wiki has always has and always will be a dumping ground of unreviewed knowledge, for better or worse.
It would already be a good first step to make that clear to beginners right there.
Oh my! This is indeed something I wish I had discovered earlier. Indeed I wish this option was available during installation.
But even with this, topics about how to manage btrfs, what are subvolumes and snapshots, what is scrubbing and why one needs it - are still relevant and important.
from purely practical standpoint I find wiki easier to search and navigate compared to nixos/nixpkgs manual pages (mainly because latter ones are just huge blankets of text, different topics stitched together into one long page). It would be nice to have a wiki to cover “non-essential” topics, provide more detailed examples on topics from manuals and stuff like that, that would just bloat the manual.
Or maybe I’m just clinging to familiar things.
We’re in a situation where any documentation resource just needs a lot of work. It can be fixed, but it will take a while.