search

NixOS / foundation

This is the home of the NixOS Foundation
61 stars 16 forks source link

Official NixOS Wiki #113

Closed Lassulus closed 3 months ago

Lassulus commented 5 months ago

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:

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 commented 3 months ago

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

RaitoBezarius commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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

infinisil commented 3 months ago

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 commented 3 months ago

Closing as it's done!

emanueljg commented 3 months ago

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?

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?

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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 commented 1 month ago

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 commented 5 days ago

@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: