Can we undeprecate/unlock the wiki?

[copumpkin]

All we have is a bunch of outdated information that nobody's able to fix now, and it's worse than before. Lots of that information doesn't make sense to put in a manual. If people find outdated or broken information on a wiki, they fix or delete it. We're short on help, and it seems like preventing others from contributing documentation in a way that almost every other project does successfully is a bad call. It's also very off-putting to newcomers.

Viable solutions, in my order of preference:

1. Unlock this wiki and figure out how to maintain quality
2. Set up an "unofficial wiki" outside of nixos.org
3. Modify the banner to link to "why we're killing the wiki, and what you should do instead to get help". The whole thing just feels user-hostile right now.
4. Take down this wiki, because it's worse than useless now full of outdated information, locked so we can't fix it, and with a banner telling people that their instincts for how to help themselves on an open source project don't apply in Nix land

cc @edolstra @domenkozar @garbas @grahamc

[benley]

Indexing the wiki would be useful IMHO, but shadowing the manuals on topics present in both is bad. (I suppose one can't specify the priority somehow.)

What if we were to auto-publish locked wiki pages which literally contain each section of the manual? The wiki would immediately contain a lot of high-quality documentation!

New official manual sections could even begin life as wiki pages, and when they reach a certain point of polish they could become part of the official manual in git and would be auto-published from then on. The "Talk" pages associated with each of the auto-published pages could be left editable for extra discussion or commentary.

Or we could try to automate adding links to the top of wiki pages matching manual sections over to the official docs. Or just strongly encourage wiki editors to link to official docs wherever possible.

[domenkozar]

So far I've seen only one argument against having PRs to merge documentation: noone will do it.

Our current data says otherwise, we've merged 17000 PRs and 300 are open, most of which are WIP.

For has:documentation tag, we merged 66 and the only two left are WIP: https://github.com/NixOS/nixpkgs/pulls?q=is%3Aopen+is%3Apr+label%3A%228.has%3A+documentation%22

Our current workflow does allow for documentation reviews and it DOES make documentation more high quality. Almost every review spotted some errors with the language if not even wrong information.

[veprbl]

@domenkozar The standards for (peer) reviewed documentation are higher. If you look at wiki edits you will see that there are much more of them than 66. The problem with PRs is not that they don't get merged, but that they are not opened in the first place.

[domenkozar]

No, our problem is that we have locked down wiki that noone can edit. Let's not make up problems that are "what if".

[copumpkin]

The bigger argument than "no one will do it" is "why do we need to be different from other projects in this?"

What makes us different from other projects that use a wiki? Do we have a value system that considers outdated/incorrect documentation to be a more serious offense than most projects? I don't know the answer, but these are all trade-offs. I don't think anyone would argue that there's zero friction to requiring review for all documentation, right? The question then is whether the added friction (ergo, lower quantity) for documentation is worth the improved quality. I don't think anyone can answer that, or that we have much evidence that would support either stance.

To me it boils down to "do we consider outdated/incorrect/sprawling documentation to be so heinous that we're willing to actually disallow a common mechanism for people to document projects?" Nobody's proposing that we don't make the manual good, or don't make a cookbook repo of endorsed cookbooks. I'm just puzzled by your insistence on actually taking the wiki down. I get that the spam issue is bad and should be fixed, but if there were no spam, would you still advocate taking it down? If so, why? Can you address my points about user expectations, friction, and the actual downsides to having a wiki?

[grahamc]

FWIW Rust replaced their wiki by using a combo of "Forge", maintained via PRs: https://forge.rust-lang.org/ and Discourse (which is a different format, but I think deserves a good look): https://users.rust-lang.org/

[Ericson2314]

I am a bit partial to PRs, but then again I spend an obscene amount of time using git. I guess more than that I like to be able to organized the docs as a whole, so mediawiki's per-page version control is not so nice.

---

@grahamc I do think Discourse / other forums are nicer than a mailing list (which is perhaps the more proximate thing Rust replaced with Discourse).

[AndersonTorres]

As a matter of obvieties:

• We have so little staff to program NixOS itself, documentation team will be invariably smaller.
• Using github would not be so bad at all, if we want to give the wiki some official status as "The NixTeam-Approved Source for Information".
• Github wikis are very professional, at least the ones I have seen.

Then, I am most favourable to a Github wiki page for NixOS ecosystem.

[ajarara]

Huh I didn't know that would show up here.

On topic: I do not think the documentation team will be smaller. There are people playing around with Nix that'd love to contribute information in an amateurish fashion who have no plans to contribute to Nix proper, and a wiki system is perfect for this.

On the contrary, I also would feel right at home contributing PR's, and this leads me to suggest that maybe the cookbook is where people like me would go, although I would rather a decision be made here.

[ericsagnes]

Just an idea, if we go for a cookbook, a way to structure and manage its content could be to have a meta.cookbook attribute for modules and packages in a similar fashion to modules meta.doc.

This will allow to automatically generate the full cookbook like the manual. But also a command could be added to generate and open the cookbook for a specific package or module on the fly, eg nix-doc xserver. (I do a similar thing for a nix based toy project, so can share the code if someone is interested) That could be especially useful if there are a lot of content in the cookbook.

(Sorry for being a little off topic.)

[crocket]

Discourse is not a substitute for wiki. It is a forum.

If you were going to set up a wiki based on pull requests, you would have to have a strong policy saying that anything that's not a spam is accepted right away without in-depth review or personal judgments of maintainers.

It should have rules that specify which pull requests are ok and prevent maintainers from imposing their personal judgments. Either, accept right away and perhaps fix it, or refuse quickly. Do not discuss whether something is wrong in a pull request. A pull request that's been open for too long provides an attack surface for trolls to create emotional dramas regarding whether it should be merged or not. They will turn pull requests into long-lasting interrogation sessions where trolls question legitimacy of a pull request as long as possible.

Believe me. Pull requests that have been open for a long time will attract trolls who want to create drama and hurt feelings.

Clear rules prevent drama and personal judgments most of the time.

I think a wiki based on pull requests would be a pain in the ass if it's not managed correctly. It takes someone who knows social engineering very well. On the other hand, a wiki that requires a strong identity should be ok.

GitHub OpenAuth on a wiki will probably work because you can report spammers on github, but there could be even stronger forms of identity like Google ID that trolls cannot just generate in large quantities. a Google ID requires SMS authentication.

[ndowens]

Personally I rather we have a wiki over just a manual; People can contribute and teach others things they have figured out that they can not share though manual

[vcunat]

Trolls: around nix(pkgs/os) I've basically never seen anything that might be even remotely considered as trolling/malicious, and these are primarily PR-based for quite a long time.

[7c6f434c]

Believe me. Pull requests that have been open for a long time will attract trolls who want to create drama and hurt feelings.

We have some hung PRs in NixPkgs (maybe unfortunately), they sometimes even provide drama, but it is purely internal — no external trolls come.

Sometimes we do see people that do not understand how the project works and try to talk us into accepting their priorities. They don't really manage to create any drama (as in discord among people with >20 commits in NixPkgs or something), even if they get a temporary ban for repetitiveness of their noise.

[crocket]

We have some hung PRs in NixPkgs (maybe unfortunately), they sometimes even provide drama, but it is purely internal — no external trolls come.

I thought something was weird when I wrote my comment, and you point it out. I have things to say about this, but I'll skip for now. It's irrelevant at this point.

I think we could reopen the wiki if only people with GitHub or Google login credentials had write access to the wiki.

GitHub accepts spammer reports, and Google requires SMS authentication.

[7c6f434c]

Erm. Isn't Google requiring SMS authentication a reason against them? I mean, it is cheap to game for a troll, and by default requires honest people to explicitly give data to one of the top-10 worst data hogs?

[crocket]

Yes, it is a reason not to use Google Auth. How do you think about GitHub Auth? Good to go?

[7c6f434c]

I dislike a lot of things about GitHub as a tool, but as long as the central repository is on GitHub and PRs are on GitHub, GitHub auth seems to be a reasonable approach for project resources with access control,

[crocket]

Why do you dislike GitHub?

[7c6f434c]

Let me just give one example: GitHub anchors (scroll-links) in issues are JavaScript-only, and if you click the link, scroll back and click it again, it doesn't work.

I also don't like Git, basically because it is not the only DVCS I have ever used.

[3demax]

Wow. As an observer I would say this is clearly bikeshedding. And I was disappointed that I couldn't make little corrections in wiki about running NixOS on arm. Worse is that I had to reach to IRC to understand what's going on. And I will have no problem opening PR to main manual, but I believe that doesn't really belong there.

Lets make this clear, there was only one problem with the wiki: a lot of spam.

Two viable solutions where proposed: a. Enable Github OAuth. Here is OAuth2 plugin I have found. b. Create static wiki and make contributions by PR.

I suggest a plan. It's simple: try (a) and see if it works. Adding auth to existing wiki shouldn't be a big deal.
If there is still a lot of spam, move to (b)

The emphasis is to do things and see how it works. I'm human too and can blast few arguments supporting either of options, but it clearly stopped being worth doing.

So here are my 2 cents: link to plugin for MW to whomever it would be appropriate. @edolstra maybe? By the time you reach to (b), I'll try to make simple comparison of most popular static sites generators.

I really like ideas behind this project and wiling to stay for a while. Hope this helps.

[vcunat]

Lets make this clear, there was only one problem with the wiki: a lot of spam.

Content maintenance was a "problem", e.g. much of it wasn't correct (anymore), but perhaps the situation has changed – the number of nixpkgs contributors has multiplied in the past few years.

[3demax]

@vcunat I think that could be figured out later, after wiki is up and running back again. Sure, document aging happens naturally as project evolves. But slightly old docs with ability to edit them are better than no docs at all.

[vcunat]

Some had argued that incorrect docs are worse than none, and we do have various other docs. I personally think it's better to peer-review even docs, but why not try the wiki again (with oauth).

[lheckemann]

I'd like to provide an additional point of view on what gap the wiki could actually be filling: besides the cookbook format that shows different possible ways of doing things, I think there's a gap in our documentation. We have:

• The NixOS manual, which is primarily a user's guide to NixOS and its (mostly) system-wide configuration options
• The Nixpkgs manual, which is a packager's guide to nixpkgs and the machinery that's in place, particularly for creating new packages.

What these two do not cover very well is a user's guide to the intended usage patterns in nixpkgs, as I noticed while working on #25274: I don't see any obvious place to document how the package should be used by users. Some stuff that's more applicable to users than to packagers (e.g. docs on the vim configuration machinery, most of the "Package Notes" section, overlays) lives in the nixpkgs manual, but it feels out of place amongst the largely more technically detailed packaging information and under the title "Nixpkgs Contributor's Guide".

Just my two cents.

[cillianderoiste]

I tried to use https://github.com/LosFuzzys/MediaWiki-OAuth2-Github but the SQL for creating tables isn't postgres compatible. I tried to hack it to work with postgres, but it then fails with an error: Exception encountered, of type "LogicException" when I don't specify a required_org. https://github.com/Schine/MW-OAuth2Client requires extra dependencies to be installed with composer, so I didn't investigate it much.

[edolstra]

See https://github.com/NixOS/nixos-org-configurations/pull/30.

[copumpkin]

Sorry, I forgot about this stuff. I'll try to pick up where @cillianderoiste this weekend.

[dhess]

Now that the wiki is shut down, where can I find the "NixOS on ARM" information?

https://nixos.org/wiki/NixOS_on_ARM

I appreciate that much of the wiki was out-of-date, but removing pages that were still relevant and have no replacement is just user-hostile.

[domenkozar]

https://web.archive.org/web/20160322211312/https://nixos.org/wiki/NixOS_on_ARM

On Tue, May 9, 2017 at 6:57 PM, Drew Hess notifications@github.com wrote:

Now that the wiki is shut down, where can I find the "NixOS on ARM" information?

https://nixos.org/wiki/NixOS_on_ARM

I appreciate that much of the wiki was out-of-date, but removing pages that were still relevant and have no replacement is just user-hostile.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/NixOS/nixpkgs/issues/22599#issuecomment-300230723, or mute the thread https://github.com/notifications/unsubscribe-auth/AAHtgzCk6168kscl9GihYUtpZskpp5Imks5r4JrigaJpZM4L8pBB .

[dhess]

If that's really your answer, the least the project could have done is replace wiki URLs with redirects to archive.org.

[vcunat]

I assume starting the wiki read-only again isn't a problem, really (for those with the access). Possibly the OAuth WIP will finish soon (as well).

[Mic92]

I and some other people have started our own wiki as it was unclear, when the official wiki will be finished: https://github.com/nixos-users/wiki/wiki

It is at the moment public editable by everybody with an github account. @dhess feel free to add a new ARM page as you gained more insights.

[dhess]

I've created a new issue for the ARM documentation, specifically:

https://github.com/NixOS/nixpkgs/issues/25653

[grahamc]

Hi @dhess, as we discussed on Twitter, I've opened a PR directing users towards Archive.org if they really must: https://github.com/NixOS/nixos-homepage/pull/139/files.

In general, much of the wiki information is not useful and has created support issues. I'm sorry this felt user hostile, my hope is that by shutting down the wiki we can more effectively move forward with more correct documentation.

Thank you for pointing out how we could have done better, I hope this change helps make the shut down more palatable.

[dhess]

@grahamc Thanks for your measured and quick response.

[grahamc]

The fail2ban wiki had spam problems too: https://www.fail2ban.org/wiki/index.php/Main_Page

Since spammers were way too much active on this wiki, user account creation has been disabled. Please, ask on the mailing-lists if you require a new user account. Thank you for your understanding and sorry about that.

Seems like a really easy, pragmatic solution. Any thoughts?

[wizzardx]

In case anyone else is looking for the Cheatsheet wiki article that was at this link:

https://nixos.org/wiki/Cheatsheet

I found a copy of that, under a different name, over here:

https://github.com/nixos-users/wiki/wiki/Nix-to-Debian-phrasebook

Also here's an archived version of the original page:

https://web.archive.org/web/20170505142206/https://nixos.org/wiki/Cheatsheet

[timokau]

I'm a beginner and just read through the manual. Ignoring the level of curation and review, I think a wiki would just be a better format.

The manual could be similar to Archs Beginners Guide (which no longer exists). It can explain the basics and link to details. That way I can quickly get an overview and then fill the gaps when I need/want to.

The current manual apparently isn't really meant to be read from beginning to end. Its more to look something up. But I think the sequential nature of a manual make it a bad format for that job.

[Mic92]

@Eisfreak7 feel free to contribute to our wiki: https://github.com/nixos-users/wiki/wiki

[benley]

Any chance we could make the link from https://nixos.org/wiki to the new nixos-users wiki a bit more prominent? Right now the page gives the distinct impression that there is no wiki, it's gone, unless you read closely and notice the small link under Community Documentation.

[Mic92]

@benley the stage is yours: https://github.com/NixOS/nixos-homepage/blob/master/nixos/wiki.html

[Mic92]

We now migrated all content to https://nixos.wiki/wiki/Main_Page It has github authentication enabled, spam protection using captchas and a fancy domain. It is administrated by @fadenb and also monitored/reviewed by the same people watching after nixos-users' wiki. I consider this issue as resolved.

[copumpkin]

Awesome, thanks! I'd mark this as resolved once we link to the wiki from the old locations. Maybe set up a redirect from https://nixos.org/wiki and mention it anywhere else we mention docs?

[Ericson2314]

It wouldn't be possible to migrate the full mediawiki history, would it?

[Mic92]

@Ericson2314 we only import the content itself.