Official NixOS Wiki

[Lassulus]

https://nixos.wiki was created a long time ago and has been useful to the community. We would now like to make the content of this wiki official.

Motivation

The current wiki has a few issues:

• An outdated version of mediawiki, which lacks many quality of life features and security updates
• A cloudflare protection that sometimes blocks editing requests and slows down the site
• A lack of active maintenance and communication from the original owner. We tried to work together with them, but they were not interested (the door is still open).

All of this creates some uncertainty and leads to some people not contributing to the wiki.

The goal is to create a long term solution with open and transparent participation.

Proposed implementation

We propose to create a new team that would be responsible for the wiki.

The software will still be MediaWiki, so we can retain compatibility with the old wiki. We already have the software, system configuration and backups available to port the data over.

We propose folding the wiki with the documentation team under wiki.nixos.org. This would also make migrating content between the wiki and the documentation more natural.

We have a team of 4 people motivated to do server administration (@Mic92, @RaitoBezarius, @Lassulus, @JulienMalka). The documentation is on board, the infra team is on board.

Team Responsibilities

The wiki team will be responsible for maintaining and monitoring the content of the wiki, as well as the system configuration.

Rollout

We propose to launch the wiki under wiki.nixos.org, and wait a few months before declaring it "official". The URL would be fixed so we don't have to migrate the content (and break references).

We merge changes from the old wiki, and point people to the new one. Ideally, automated. Ideally with the help of the old wiki maintainers.

What have we already done

We prepared a NixOS wiki configuration that can import the current wiki content.
It provides Authentication through email or Github Login. In the process we improved
the upstream mediawiki module in nixpkgs.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/official-nixos-wiki/38715/1

[infinisil]

Great initiative!

Regarding the domain, https://github.com/nix-rfc-canonical-domain/rfcs is an RFC draft to unify nix.dev and nixos.org into a single canonical domain, currently proposing to move everything to nix.dev, but I think a two-step process would be better:

• Move nix.dev under nixos.org as docs.nixos.org, which establishes the canonical domain goal with minimal changes
• Optionally in another step, the entirety of nixos.org could be moved to nix.dev (or another domain), but that's a much larger hammer and not really necessary

But considering that, I think it would be better for the wiki to use wiki.nixos.org, such that we limit the domain spread.

[Lassulus]

But if the proposal is to move everything to nix.dev shouldn't we move the wiki also there? moving a domain later is very bad for a wiki SEO wise, which is also a concern we have with the old wiki.

[infinisil]

@Lassulus Yeah I don't think everything should be moved to nix.dev anymore, at least initially. Having a canonical domain, whatever it may be, is a first goal, and we're almost there with only nix.dev being out of line. I'll probably change the RFC draft there to just propose moving nix.dev to docs.nixos.org. In fact, we probably don't even need an RFC for this, we should be able to do that with consensus in the docs team.

[deviantsemicolon]

Great initiative!

Regarding the domain, https://github.com/nix-rfc-canonical-domain/rfcs is an RFC draft to unify nix.dev and nixos.org into a single canonical domain, currently proposing to move everything to nix.dev, but I think a two-step process would be better:

* Move nix.dev under nixos.org as `docs.nixos.org`, which establishes the canonical domain goal with minimal changes

* Optionally in another step, the entirety of `nixos.org` could be moved to `nix.dev` (or another domain), but that's a much larger hammer and not really necessary

But considering that, I think it would be better for the wiki to use wiki.nixos.org, such that we limit the domain spread.

Would nixos.org become a redirect to nix.dev so outdated links don't break?

[mightyiam]

Feedback. I don't like the referring to Nix as NixOS such as in nixos.org domain.

[infinisil]

@deviantsemicolon @mightyiam For such feedback to the RFC draft, please instead give it in https://github.com/nix-rfc-canonical-domain/rfcs by opening an issue or a PR (in the spirit of NixOS/rfcs#138).

[Melkor333]

Thanks a lot for this proposal! It's about time :)

Are there any plans to improve content quality aswell?
E.g. is the plan that the documentation team would be focussing on improving these docs?
Or complex new nix features require an entry in the wiki to be merged?

I also remember some discussions on "content ownership". Like some wiki pages are "owned" & maintained by e.g. the maintainers of related packages... (Given this is all on a voluntary basis I'm not sure that would help much, though)

[fricklerhandwerk]

This is a great initiative, thanks a lot @Mic92 and @Lassulus! From the development perspective I strongly support having a Wiki about NixOS, because it lowers the threshold to contributions where they lack most.

As proposed in the Wiki development Matrix room, and similar to what I wrote elswhere:

1. Please put the wiki under nixos.org.

   It's mainly about NixOS already, and this is where the coverage and quality of documentation is currently worst.

2. Make it absolutely clear that the Wiki is about NixOS and state its exact purpose.

   Everything else sort of works - independently of NixOS - with reference documentation (Nixpkgs and Nix manuals) and a bit of guidance (nix.dev). A Wiki won't help in those places, and will be counter-productive to the currently ongoing homogenisaiton and centralisation.

3. Let's resolve the broader domain issue independently.

   There seems to be no clear consensus yet over the target audience (developers vs many more are quite representative), and no consensus on whether to have "one big product" or rather an ecosystem of many independent but related components, or a strategy for how to make any option actually work well - currently it feels like we're in an uncanny valley in between. We cannot, and therefore should not attempt to, solve that right here where it's essentially about re-establishing an existing resource.

is the plan that the documentation team would be focussing on improving these docs?

@Melkor333

It would be great to have people focus on NixOS documentation generally. I hope that the Wiki will make that easier and more likely to happen. The current documentation team doesn't have much capacity for that. Our current strategy is to make improvements from the bottom up, starting at the Nix manual, which implies that NixOS will come last.

Of course anyone is invited to just go ahead and do things they find important! As a team we will help guide users and contributors to the right people and places. We will definitely advertise the official Wiki as a source for NixOS information, which is a lot easier if it has a clearly defined purpose.

[MatthewCroughan]

One thing that has prevented me from contributing to nixos.wiki in the past is attribution. It's not clear who contributed the content. The knowledge is given for free, just as code is. But we should be able to see who wrote it, and a clear edit history like Wikipedia, or git commits. I think this would increase content quality because people would be likely feel more responsible for the content they produce, and be proud of the contributions due to the attribution, as is also true of pull requests and merge reviews.

Edit: It looks like the edit history is available, but hidden unless you log in, as the theme is hiding it unless you're considered an 'editor'. You can log in with GitHub now too. Still, attribution feels hidden, I would like to see a theme that puts the attribution and edit history front and center.

100% would like to see an official wiki and look forward to contributing.

[Pablo1107]

1. **Please put the wiki under nixos.org.**
   It's mainly about NixOS already, and this is where the coverage and quality of documentation is currently worst.

2. **Make it absolutely clear that the Wiki is about NixOS** and state its exact purpose.
   Everything else sort of works - independently of NixOS - with reference documentation (Nixpkgs and Nix manuals) and a bit of guidance (nix.dev). A Wiki won't help in those places, and will be counter-productive to the currently ongoing homogenisaiton and centralisation.

I think there is a place for non-NixOS use cases in the wiki. There are a lot of Nix users (like myself) that uses Home Manager, Nix Darwin and other community projects that helps using Nix on several devices. It would be nice to have all the content for how to use Nix for some of these alternative use cases covered.

Just to name an example, say you have an article about some GUI application and how to install it and use it in NixOS, but have a note in the article stating that for non-NixOS users you would need to wrap the application with NixGL which is a common problem someone would face trying to install a GUI application and have a link to the NixGL article stating the different ways to use it.

[Mic92]

I guess we go for wiki.nixos.org than, I wasn't in sync what the plans with nix.dev were.

[infinisil]

2. Make it absolutely clear that the Wiki is about NixOS and state its exact purpose.
Everything else sort of works - independently of NixOS - with reference documentation (Nixpkgs and Nix manuals) and a bit of guidance (nix.dev). A Wiki won't help in those places, and will be counter-productive to the currently ongoing homogenisaiton and centralisation.

I don't think it's reasonable or realistic to try to enforce it being only for NixOS. People will write entries for whatever they think is worth writing down. We absolutely do still need properly reviewed documentation, but not everybody can spend weeks on PR back-and-forths.

So the choice is not between reviewed documentation and unreviewed wiki entries, but rather it's between lower-quality wiki entries and it not being written down at all, or somewhere else (such as the old wiki).

We should think of the wiki as a breeding ground for documentation. It can give us a good sense of what needs to be documented, striving to not need the wiki at all.

The current documentation team doesn't have much capacity for that. Our current strategy is to make improvements from the bottom up, starting at the Nix manual, which implies that NixOS will come last.

To clear this up: You're focusing on that, but everybody else from the docs team is doing different things :)

[Majiir]

Just as the Arch wiki is useful for users configuring software on other distros, so too can the NixOS wiki. NixOS is simply the project where users are likely to be using Nix and Home Manager and NixOS services and...

So, being not a foundation member or docs team member but a user, nixpkgs contributor, and very-small-time nixos.wiki contributor, I think wiki.nixos.org is a natural home for all things Nix.

Looking forward to seeing wiki improvements in any case!

[nstgc]

Just as the Arch wiki is useful for users configuring software on other distros, so too can the NixOS wiki.

I don't think that's a fair comparison. By design, Arch Linux is as generic as reasonably possible while NixOS goes in the opposite direction.

[RaitoBezarius]

Just as the Arch wiki is useful for users configuring software on other distros, so too can the NixOS wiki.

I don't think that's a fair comparison. By design, Arch Linux is as generic as reasonably possible while NixOS goes in the opposite direction.

I think we were talking about the context of Nix-derivative distributions, not any distribution. So I think that's a fair comparison.

[zimbatm]

Added this to the foundation agenda for discussion next Tuesday. We'll give you an update them.

[infinisil]

Added this to the foundation agenda for discussion next Tuesday. We'll give you an update them.

I actually don't think the foundation needs to or even should be involved in deciding over this, because this is strictly a non-administrative topic.

If there was any sort of controversy around doing this I'd propose an RFC, but at least from the reactions to this issue, that doesn't appear to be the case, so there's no need to have an RFC.

So really I think the next step here is doing this! 🚀

[thufschmitt]

I actually don't think the foundation needs to or even should be involved in deciding over this, because this is strictly a non-administrative topic.

It should not, but the board is currently the only instance with the ability to make a decision on such a thing if they get blocked by any reason, which is why this was escalated there (anyone, correct me if I'm truncating the history).

At any rate, we should give this a few more days to give everyone a chance to voice their opinion.

[infinisil]

It should not, but the board is currently the only instance with the ability to make a decision on such a thing

This directly contradicts this sentence on the foundation board page (Edit: Actually not directly, but you get it..)

The board is not responsible for technical leadership, decisions, or direction.

And it's not just in writing, I also remember hearing the foundation board mention this. If even at all, this should be a last resort option.

if they get blocked by any reason, which is why this was escalated there

I cannot remember or find any instance of this being blocked in any way before. If that actually exists, please link to it or give more context.

So to me it looks like it's absolutely not the foundation's decision.

[RaitoBezarius]

It should not, but the board is currently the only instance with the ability to make a decision on such a thing

This directly contradicts this sentence on the foundation board page:

The board is not responsible for technical leadership, decisions, or direction.

And it's not just in writing, I also remember hearing the foundation board mention this. If even at all, this should be a last resort option.

This is not a technical decision, is it? This is a political decision to promote this instance of the wiki as the *official one.

Foundation still retains the image dimension of the various official websites they are endorsing.

This is not really an issue on should we use that technology or this technology, this is really just about promoting a copy of nixos.wiki as an official wiki with a different administration team (:= political).

if they get blocked by any reason, which is why this was escalated there

I cannot remember or find any instance of this being blocked in any way before. If that actually exists, please link to it or give more context.

So to me it looks like it's absolutely not the foundation's decision.

There's a bunch of context across the years on the problem surrounding the old wiki, this was raised because there are multiple candidates for being promoted as an official wiki, I do not want to link to it because I don't want to shake the hornet's nest needlessly.

People have been working on this project at least for the last year, it was indeed blocked on "decisionmaking".

[infinisil]

@RaitoBezarius Fair, you make good points. So this is directly related to #39, because we'd be setting the precedent that the NixOS foundation can decide over what is official. And I'm really not sure if I like that idea, because it doesn't involve the community much.

But we do have a way of deciding things officially that involves the community: RFCs. Yeah I know there's problems with RFCs, and I'm trying to improve it (stuck waiting for shepherds..), but that would really be the best way to do it then. And if you have shepherds, RFCs can be done in a couple weeks.

I'd be willing to either author/co-author or shepherd such an RFC. The issue description is pretty much in RFC format already, so it's very easy to do, and it seems like there's consensus around this already, so if we get some other shepherds this is gonna be a quick thing.

[RaitoBezarius]

@RaitoBezarius Fair, you make good points. So this is directly related to #39, because we'd be setting the precedent that the NixOS foundation can decide over what is official. And I'm really not sure if I like that idea, because it doesn't involve the community much.

I understand that feeling and I believe it is very much shared inside the Foundation, that is, we are already in a last-resort situation: the sad state of wiki is hurting a lot of folks and I think you are totally right that we need to separate this exceptional event and not reuse it as a precedent.

But we do have a way of deciding things officially that involves the community: RFCs. Yeah I know there's problems with RFCs, and I'm trying to improve it (stuck waiting for shepherds..), but that would really be the best way to do it then. And if you have shepherds, RFCs can be done in a couple weeks.

I still don't really agree (but I didn't have time to get back to you on other channels) with this framing of RFCs, Bootspec v2 is yet another excellent example, had plenty of shepherds, but the momentum is kind of killed.

I'd be willing to either author/co-author or shepherd such an RFC. The issue description is pretty much in RFC format already, so it's very easy to do, and it seems like there's consensus around this already, so if we get some other shepherds this is gonna be a quick thing.

All that I hope for is that this does not put further churn on people trying to get this somewhere, which is the real focus of the operations, not the excessive bureaucracy that we inflict ourselves for the sake of a governance that tends to burn out people in general, at least, for the time being. I would reserve it for more high stakes decisions, IMHO. Here, we are talking about deploying a wiki…

[infinisil]

I still don't really agree (but I didn't have time to get back to you on other channels) with this framing of RFCs, Bootspec v2 is yet another excellent example, had plenty of shepherds, but the momentum is kind of killed.

RFCs can have widely different scales. The bootspec one attempts to create a new version of a specification, with all its intricacies. This is no easy feat and takes time. As does the Nix formatting RFC, it's been in progress for over a year!

However for making the official wiki, there's really just these points:

• Creating an official wiki at wiki.nixos.org.
• Deciding the initial team in charge of it.
• A rough declaration of the purpose, to be put on the landing page (that's the main thing that needs to be discussed)

This is very small in scope, which is why this could be done very quickly.

Really this could be the start of a policy for making projects official properly, the above three points seem fairly universal for that.

In fact the Nix formatting RFC has pretty much those exact points as well, indeed it's also about making something official.

[mikunimaru]

I think it would be ideal to be able to manage article content on github. The de facto center of the nixos community is github.

[asymmetric]

@infinisil @RaitoBezarius I see the point about involving the community and think it's important. We could try with an RFC and if it ends up stalling without controversy, have the Foundation take the decision. This would effectively delay the wiki by some weeks, which may or may not be a big issue.

In case we decide to go ahead with the RFC, I'd be available as a shepherd.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/official-nixos-wiki/38715/5

[zimbatm]

Our Tuesday foundation meeting was pushed to today, where we briefly discussed this topic. We don't think we need to make a decision on this. We are here to unblock, and there is already a consensus on wiki.nixos.org. So let's go.

[infinisil]

@fricklerhandwerk @Lord-Valen Can you expand why you downvoted @asymmetric's comment? Because there's three separate mentioned points in it.

Regarding the foundations meeting, I think it's great that you aren't making a decision on this, but I'm not sure why people seem to celebrate that.

@Mic92 @Lassulus @RaitoBezarius @JulienMalka: My offer still stands, I can author or shepherd an RFC on this. If some of you and @asymmetric (or others in this thread) volunteer as shepherds, we can have an official shepherd team and initiate FCP immediately. Since there's widespread approval of this idea already I expect it to go through without hickups. Just let me know and I'll initiate it.

[cig0]

@infinisil "[...] because we'd be setting the precedent that the NixOS foundation can decide over what is official. And I'm really not sure if I like that idea, because it doesn't involve the community much."

But doesn't the foundation populate its seats with folks drawn from the community? 🤔