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.

[itslychee]

So what will happen with https://nix.dev now that https://wiki.nixos.org exists?

[RaitoBezarius]

So what will happen with nix.dev now that wiki.nixos.org exists?

nix.dev is not a wiki, it won't disappear, it's a complementary approach.

[nixos-discourse]

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

https://discourse.nixos.org/t/wiki-nixos-org-is-now-live/42570/28

[wrycode]

nix.dev should be moved into the new wiki. What's the point of keeping it on a different domain?

[infinisil]

nix.dev is maintained and reviewed by the docs team. If you propose a change to it, it will get discussed and reviewed. This makes contributing harder, but the quality will be better. We also try to focus on tutorials and guides, especially for beginners. The reference docs are also slowly being hosted on nix.dev.

In turn, anybody can edit the wiki, making contributions very easy, but the quality won't be as good. The wiki is a good place to incubate new documentation, which could then be moved to nix.dev later.

Regarding it being a separate domain, that's a different question, we'll probably move it to docs.nixos.org at some point: https://github.com/NixOS/nix.dev/issues/869

[zimbatm]

Closing as it's done!

[emanueljg]

The reference docs are also slowly being hosted on nix.dev.

So reference docs can now exist on either the (three) manuals or nix.dev? How do I know where to look for what?

(...) anybody can edit the wiki, making contributions very easy, but the quality won't be as good. The wiki is a good place to incubate new documentation, which could then be moved to nix.dev later.

The problem is the same as above. OK, let's assume 50% of the wiki documentation is considered good enough. Does it get cut-and-pasted or copy-and-pasted?

• if it's cut: then we have 50% of documentation in one place and 50% of documentation in another, further exacerbating the issue of the documentation jungle. Essentially, you have now split the NixOS wiki in 2. How is that an improvement?. And how would that work when half of an article or half of a set of articles would work, How is that an improvement?
• if it's copied: then we have duplicate documentation which is 10 times worse.

nix.dev won't be able to keep up with the pace of information regardless, so things will become out-of-sync and outdated.

We have gone from 3 to 4 places to look for reference documentation. We have gone from 1 to 2 places to look for "layman" documentation. The complexity in knowing where to look for documentation has risen into the stratosphere:

1. Do I want reference documentation or not reference documentation? What's the difference? Will I know as a user what the difference is?
2. If reference, which 1 of the 4 places should I look?
3. If not, which 1 of the 2 places should I look?

It's absolutely ridiculous. Do you know what a new user ACTUALLY wants?

• "Where's the docs"
• "Here: (ONE link)
• "Thanks!"

This shoehorning of nix.dev seems to be more an issue of coddling documentation writers, rather than having the best interests of the new user at heart, which I think is downright appalling. It's going to make the infamously bad Nix(OS) documentation even worse and it will hurt new users the hardest.

Either we put nix.dev offline until it has absorbed all reference docs or we have no wiki. There are no other good options.

[zimbatm]

It's good that you care about having good user documentation.

When doing community work, the path forward is not always obvious. We all have different ideas, and then the question is; what strategy should we adopt? There are two general approaches: (1) come up with the perfect solution, and (2) try a bunch of things. Regarding documentation, we've been stuck in (1) for a long time. So now we are doing (2). That means that there is going to be some expansion for a bit. Then in the medium term, I am confident that we will find a new local optima and be able to contract things again.

[eclairevoyant]

The one link can just be nixos.org/learn. Or if you've bookmarked a link on a specific topic, send the bookmark.

anybody can edit the wiki, making contributions very easy, but the quality won't be as good

I think I'm more disappointed to see we've given up on quality despite just launching. Rather than creating the n-th dead wiki, why is there no appetite for moderation, automation, style guides, etc. as every successful wiki has?

[emanueljg]

There are two general approaches: (1) come up with the perfect solution, and (2) try a bunch of things. Regarding documentation, we've been stuck in (1) for a long time.

How has the "perfect solution" been tried? I'd argue (2) has already been tested for a long time too. We've at the very least had the manuals and the wiki - "a bunch of things" (4 sources). The experience has been awful.

So now we are. That means that there is going to be some expansion for a bit.

That war of attrition has already been tried once in manuals vs wiki. It failed miserably. We need to try to practice restraint for once, not frivolous expansion.

I am confident that we will find a new local optima and be able to contract things again.

You consider things "contracted" as they currently are? And what do you mean by "contracted"? What is the end goal?

[emanueljg]

The one link can just be nixos.org/learn

Which is a meta page that links to multiple different places and strawmans my point...

Rather than creating the n-th dead wiki, why is there no appetite for moderation, automation, style guides, etc. as every successful wiki has?

I agree. The way the vision for the new wiki has been described by @infinisil makes it sound more like a containment area for subpar articles rather than good documentation in its own right.

[nixos-discourse]

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

https://discourse.nixos.org/t/help-wanted-updating-links-to-point-to-the-new-nixos-wiki/45185/1

[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? :thinking: