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

[abbradar]

I think I haven't voiced my concerns when we killed the wiki but I should now (even if I did it already after all :D). My main argument contra deleting the wiki is that a lot of information there IMHO doesn't belong to the manual.

Why should it contain examples on how to compile Android sources under NixOS? Or -- what are current problems with specific Steam games and how one can workaround them? That's just my personal pain points, but a lot of Linux distribution know how is in an exactly this form (hey, I have an obscure use case and want to describe it for other people).

First thing that comes to mind apart from wiki is blogging. But blogs are fragmented, have different levels of quality, search is difficult unless you have the keywords very right or blog is more or less promoted. Blogs are also egocentric -- and that's a good thing, because first and foremost blogs are for expressing opinions and experience of individual people. Ideally (I think) technical blogs have the spirit of academic papers -- people describing problems and their solutions, competing each other for the best one and discovering things. But I won't search for an academic paper the first thing when I want to solve a problem -- I'll search on Wikipedia to have a broad view and possibly accepted good-enough solutions, hopefully up to date.

And that's what I expect many others to do, too. Different people have different ways of obtaining information, but having a centralized repository of not-surely-true-but-close-enough information without any official warranties feels a good idea. Arch (and Gentoo, not as good IMHO but very nice too) does this awesomely and I understand that we won't come anything close for observable time -- when I want to learn about a new Linux-related topic I'll go to ArchWiki (even nowadays). Manuals, on the other hand, feel like white papers to me -- they are awesome for getting a hang, but not (intuitively) for learning about and solving obscure edge use cases and quirks. Why would something like this have a place in the manual and who would take responsibility for ensuring those workarounds are still true there (which is, again, an "official" information source)? Would he/she test them each release?

Maybe I just don't get what the manual should look like ;)

[grahamc]

Since you singled me out, I think something outside of the manual is helpful, as lower quality contributions can still be very helpful. Frequently, when I was first learning, the wiki would be wrong in some cases but was still enough to help me find the solution. Spam is a difficult and frustrating issue ... I don't know what a good solution is for that. I've been eyeing Discourse.org. It isn't much of a wiki, but is interesting in that it seems to be append-only: spam can only be added, not ruining existing content.

[AndersonTorres]

What about the "NixOS Weekly"?

2017-02-09 23:44 GMT-02:00 Graham Christensen notifications@github.com:

Since you singled me out, I think something outside of the manual is helpful, as lower quality contributions can still be very helpful. Frequently, when I was first learning, the wiki would be wrong in some cases but was still enough to help me find the solution. Spam is a difficult and frustrating issue ... I don't know what a good solution is for that. I've been eyeing Discourse.org, but it isn't much of a wiki.

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

[abbradar]

Obvious question -- how does Arch combat spam? I haven't seen much junk articles there. In my experience, asking a simple question which a robot doesn't expect (I used "what is derivative of x^2/2?") works wonders, until someone targets you specifically. I don't think it'd be enough for us.

[Baughn]

To quote from the Arch wiki: "You must create an account before being able to edit ArchWiki articles; answering the captcha question requires an up-to-date Arch Linux environment: non-Arch users are very welcome to contribute to the wiki, and in order to answer the question they can for example boot into a live Arch system with the latest installation image."

I think that would work fine for NixOS as well. The intersection of "Spammers" and "Nix users" is probably acceptably small.

[domenkozar]

I think wikis require lots of supervision to be efficient. Not to mention how gentoo lost wiki content years ago due to lack of backups.

I agree we need other resources for documentation besides manual since not everything belongs there.

I started http://nix-cookbook.readthedocs.io/en/latest/ some time ago, if there is interest we can migrate non-manual content there.

[edolstra]

@abbradar We had a challenge question on the wiki, which worked for a while. Until it no longer worked and we had a new spam invasion. Several times I had to spend a day to clean up wiki spam, which is not really a fun thing to do.

IMHO, the most straight-forward thing to do is create a GitHub wiki. That should take care of the spam issue. Also, many (most?) potential contributors will already have GitHub accounts so they won't need to register to edit the wiki.

However, if we revive the wiki, we do need people who are willing to invest time in keeping it in shape, editing articles, structuring the wiki, weeding out outdated info, and so on. Otherwise you just end up with a dumping ground of potentially outdated, wrong or badly written info, which is not necessarily the sort of thing you want associated with a project. We did have some people doing wiki maintenance, which is much appreciated, but I don't think it was enough if we want to have something resembling the Arch wiki.

(See also @peti's remarks on this: http://lists.science.uu.nl/pipermail/nix-dev/2016-February/019513.html)

If there are volunteers for maintaining the wiki, I can create an empty nixos-wiki project on GitHub with a world-writable wiki. (The wiki could also be associated with one of the existing repos, but since it's supposed to be for all Nix-related projects, it probably makes more sense to have it separate.)

[domenkozar]

I think wikis require lots of supervision to be efficient.

To prove my point :)

[Baughn]

A world-writable wiki is probably the worst of all worlds. It'll get spammed into oblivion instantly; there are bots constantly trawling the internet for that sort of thing.

If we're going to have a wiki, even an empty one, then it should have mandatory registration (or some sort of captcha) right from the start.

[abbradar]

@edolstra First, I completely agree that cleaning spam is not a fun thing, and I remember it was one of main points (apart from supervision) to bring the wiki down -- that's why I didn't oppose it.

I also agree with you and @domenkozar that wikis require supervision but we don't want to have something like ArchWiki. Let me explain -- ArchWiki is not only a source of community pieces of advice and case studies, it's also an official source of documentation: they don't have a manual like us. I feel that our old wiki was also serving as an excuse for us doing a bad job with our documentation. That was very bad, and we have, in my opinion, greatly improved since the wiki was killed -- this movement mobilized people willing to improve our manuals, and they did (and continue!) a marvellous job.

What we, IMHO, do want (and a lack of which I feel) is a centralized place to store things which are difficult to place in the manual (examples are in my previous post). A wiki may be one solution, the other, suggested by @domenkozar, is to maintain a community cookbook. Sadly I don't have much experience with this concept (I haven't seen other projects doing this and am interested in good examples -- and by that I don't mean that I feel sceptical). It's interesting if it can also fill the void.

[domenkozar]

Example of a cookbook that works: http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/

[edolstra]

With "world-writable" I meant editable by anyone with a GitHub account.

[abbradar]

I say let's try using @domenkozar's cookbook idea, if only as an experiment. We have already tried a wiki :D Personally I can't compare those ideas because I haven't tried working with the former, so surely there are better arguments for or against -- count me as +0.5.

[edolstra]

I think the cookbook can be a section of the wiki. Unless you want the cookbook to be strictly curated (i.e. requiring changes to go through pull requests), in which case it would not be a substitute for a wiki. Also, looking at https://nixos.org/wiki/Main_Page, many articles there don't really fit under the cookbook category (e.g. the FAQ or the community section).

[domenkozar]

Cookbook is a meta name just as the wiki, really both terms are overloaded. I see no reason we couldn't have FAQ in the cookbook (or we can call it something else, like meta docs).

I'd say cookbook goes through PR, but it's easy to contribute, you can use github just like the wiki. Same would apply if we used github wiki really.

[7c6f434c]

I guess if we have a PR-based Cookbook, its pending PRs would develop a useful life of its own…

[edolstra]

Yeah, if you need to fork it on GitHub and make a PR for every change, it's not really a wiki... I assume that most people who want a wiki, want something with very low friction to edit.

[copumpkin]

We have already tried a wiki

So have dozens of other projects that seem to get it working just fine. My main concern is for optics and practicality.

1. Optics: people from all over know what a wiki is. Pages from our "wiki" are often the first result on every google search about Nix. I've known at least one person get seriously turned off when seeing a wiki with a big banner across the top that tells you not to use it, when it seems to contain (to a newcomer at least) valuable information. It frustrates project members because we can't fix bad information in there. Limiting it to a GitHub wiki or to PRs against a cookbook basically limits our documentation base to people who are comfortable contributing to open source projects, and makes the activation energy for "I just figured out how to do a thing on Nix[OS], let me tell other people" much higher. I'm not saying it should be world-editable, but the hundreds of successful wikis out there should demonstrate that there are ways to keep a running traditional wiki that doesn't get overrun by spam.

2. On practicality of the cookbook PR system: we already struggle to get code reviewed, and the project is always short-staffed. Do we really want to introduce yet another review burden for contributions? I get that misleading documentation is bad, but there are pros and cons to both sides.

Anyway, I just think that "we tried a wiki, got overrun by spam, so wikis aren't for us" is flawed reasoning. If we want GitHub sources of identity, we can OAuth against GitHub; furthermore, we can spread out the burden of spam cleanup on the mediawiki, because it's not right that @edolstra has to deal with all of it. But let's not throw the baby out with the bathwater. There's lots of reasons people want wikis, primarily because they're pretty free-form, unstructured, and low-overhead to collaboration/sharing. Trying to impose more central control/structure on it can be a fine strategy for some kinds of documentation, but it scratches a different itch.

[copumpkin]

Also, I think there's a reason not many people use GitHub's native wiki; I don't particularly like reading or adding documentation to it. I haven't put my finger on why, but do any of you use them regularly? Put yourselves in our users' shoes.

[edolstra]

I'm not opposed to turning the wiki back on with GitHub OAuth for authentication. If somebody wants to do a PR against https://github.com/NixOS/nixos-org-configurations to enable it, and if there are people willing to commit to maintaining the wiki, I'm all for it.

[copumpkin]

@edolstra if others don't think it's a terrible idea to reopen it, I'd be all for that and willing to contribute some time to either or both of those activities you mention.

One question first though: what was the wiki admin structure before it got locked? Were you the one cleaning up spam because few others had the power to do so, or was it because nobody else ever put in the time? I've never been deeply involved in a mediawiki so I don't really know how that sort of thing works or worked in our implementation.

I also don't want to diminish the cookbook idea. I think there's space for a variety of degrees of curation and flavors of documentation. There's room for blog posts, wikis, curated cookbooks, free-form lists of resources around the web, FAQs, and other things I haven't even thought about. I do think a wiki is a fairly natural place to "index" out to other forms of documentation, since for better or for worse a large number of people expect them to.

If we reopen the wiki, I'd probably want to adopt @garbas's work (I think there are tons of issues in here) on indexing, sorting through, and possibly even deleting (in the case of severely outdated/incorrigible information) the existing wiki pages.

[FRidh]

I'd say cookbook goes through PR, but it's easy to contribute, you can use github just like the wiki. Same would apply if we used github wiki really.

I agree with this.

I would like to see the peer-review to at least keep some quality. Since you can modify and open a PR through the web interface it is a true substitute for wiki's. I personally prefer to just clone the repo and make changes. Not being able to do that is exactly what discourages me to contribute to typical wiki's.

We could have a separate group in the NixOS organization that has commit rights to this wiki repo. I suppose this group eventually becomes bigger than the group that has Nixpkgs commit rights.

And, if we have some kind of maintainer file for the wiki, we could use a bot that merges PR's of maintainers without handing out commit rights.

[domenkozar]

Just as with code, there needs to be reviews for documentation. Otherwise you just postpone the problem and the result is the current wiki. That's why I think having a way to review what goes into community managed docs is important.

[expipiplus1]

I'd like to put in a vote for a PR based wiki. With this one gets all the advantages of github project management for free:

• Little spam, I can't recall ever seeing a PR on a github project which wasn't trying to be constructive
• Easy feedback on changes, reviewing PRs is pretty simple
• People are familiar with the process of making changes, I imagine that most people who will contribute to the wiki will be familiar and comfortable opening PRs.
• Issues
  • Can be raised against outdated/incorrect information
  • Can be linked to the other NixOS projects.

Opening new PRs for small changes isn't very hard at all. All text based files on github have a little edit button next to them which will automatically open an editor for fixing those little typos. For larger edits, proper version control is there, and people can use their own machine and editor.

[copumpkin]

I think documentation is fundamentally different from code, in that it gets exercised invisibly, unlike code which breaks fairly obviously. Code reviews can guard the entry point into a repo, but what keeps the code healthy after the review, in the presence of an evolving project, is that we're running it all the time.

Reviewing documentation up front is great (but I wish y'all would acknowledge the costs of it and stop just saying "it needs to be done" without justification) but doesn't address that it gets out of date. We need ongoing, post-submission review/maintenance of documentation, and that will be a fundamentally different process from what we do with a codebase. I'd argue that as time progresses, the maintenance becomes the bigger burden, and looks very similar in a wiki and a PR-based system, except that the latter one has more friction.

I also disagree that "all documentation contributors will be comfortable making PRs". It's a very OSS-developer-centric view of the world, and while I wish it were true that people make PRs on the drop of a hat, it's not. We've been doing this for too long, and what feels natural for us is not necessarily what's good for all users. I recognize that on some level our users are fundamentally more technical than most, but we're a niche inside a niche inside a niche, and I'd like to break out of at least one level of that nesting. We have a hammer we use many times a day, but not everything is a nail...

[FRidh]

Reviewing documentation up front is great (but I wish y'all would acknowledge the costs of it

Is it high? I recall claims that people don't like writing docs, so if that really is the case, we likely won't have much to review.

We need ongoing, post-submission review/maintenance of documentation

Absolutely.

I'd argue that as time progresses, the maintenance becomes the bigger burden, and looks very similar in a wiki and a PR-based system, except that the latter one has more friction.

Exactly which friction? Creating a PR, or the reviewing? If you use a Wiki, you have to use a website, make all your changes at once, or they'll be lost. If we use a GH-based wiki, you can do the exact same thing with the webeditor, but you also have the possibility to clone and make changes locally.

The only difference that remains is the reviewing. Here I think having a bot that merges PR's of maintainers is a solution to reduce the friction for maintainers of articles.

[7c6f434c]

As for spam on MediaWiki and its cleanup: I remember that at some point the bad guys replaced the main page with a redirect to a redirect to a page with garbage, and they also did some trick to disconnect the history (maybe they have renamed the original page so that history moved to another place?), and it wasn't obvious to me how to roll this attack back.

About nicheness: it is still hard to skip the steps. For example, NixOS users right now are still expected to be able to mount a partition manually using the command line during the installation. If we don't plan to remove this «requirement»/«limitation»/«expectation» soon, we might try to figure out what other skills people at this level have more often than not.

And if there is a plan to make sure that people with less sysadmin skills can still install and use NixOS, targeting of the articles to different user skill levels will also be a significant problem to remember.

[copumpkin]

@7c6f434c I'd try to remember that Nix is far easier to get started/productive with than NixOS, and requires a much lower commitment (i.e., I run a curl | sh on any Linux or macOS or even Windows nowadays). Not everyone jumps straight into NixOS, so don't assume that all wiki consumers would be linux experts or even FOSS contributors. As an example, last I looked the easiest way to use ghcjs was to install nix, and a major online guide to ghcjs just told people to do that. Those are people who might not know or care about low-level linux-isms, but still want to understand and use Nix. I'm also seeing random other FOSS projects that have default.nix in the root of their repo, and users of those projects don't necessarily even care about Nix, but might be intrigued by the potential when it simplifies their hacking. These folks are probably willing and able to consume a wiki, but to them Nix is already a yak shaving expedition (hopefully a pleasant one) along the path of doing what they actually care about, so minimizing friction for them still seems important.

@FRidh I'm just saying that the GH-based webeditor doesn't get used very much in practice (do you enjoy it? Do you expect most people to want to go through a review session to fix a three-character typo they saw while installing Nix to run ghcjs?), and I'd rather not be trailblazing new ways to do documentation in a small project that we're trying to draw new users into. The more we differ from the rest of the world, the more hurdles we have to clear to gain adoption. I just want to differ in the ways we do well (the actual packaging), and stick to reasonably tried-and-true models for things we aren't experts in. I realize we have lots of opinions about how documentation should work, but is this the place to experiment with it? Community/adoption is hard to build and in many cases easy to lose.

[7c6f434c]

Right, I was evaluating Nix-only setup considering a proper multi-user setup with a daemon (this does require knowing what you are doing).

That probably means I should be more careful on IRC when recommending debugging strategies that require too much understanding of the standard system stuff…

[copumpkin]

Well, I don't know! As always it'll depend on the audience 😄 I've just been trying to spread the Nix word/gospel to folks who mostly don't do low-level linux stuff recently and am getting a lot of feedback about things like this. Perhaps also worth pointing out that I'm passing on the feedback rather than them providing it directly, which might give a glimpse into different sorts of people whose first instinct isn't always to submit a PR, but can still have valuable input (or at least I like to think so).

[FRidh]

I'm just saying that the GH-based webeditor doesn't get used very much in practice (do you enjoy it?

Try it! I think it works well and is just as good, if not better, than the (basic) editor of say Mediawiki. The editor supports highlighting, indentation, preview. When you're finished writing you give the change a (terse) title and optional description (as you should also do with a wiki) and then select whether you want to commit directly (if you're allowed to) or open the change as a PR. The only advantage of Mediawiki I can think of is the edit buttons at all the headings. And, to be fair, that is a big advantage.

[copumpkin]

Try it! I think it works well and is just as good, if not better, than the (basic) editor of say Mediawiki.

I have used it 😄 I'm just saying that people don't do this much. My concern is exactly your "or open the change as a PR" bit. The people most of this discussion is about are overwhelmingly not the folks who have direct merge powers, so we're basically saying every little documentation change would be a PR, and to many people that is either an unfamiliar concept that they now need to understand (thus discouraging them from fixing or contributing), or a familiar one that might dissuade them from making a three-letter fix to a typo they found. I'm not saying it's actually that much work in practice for them (assuming they push through it and learn that it's not that bad), but the initial perception matters. PRs and commits are second nature to most of us, but I'd be fine editing a wiki in vim on vt100, and my convenience isn't what I'm trying to optimize for here. Everyone understands a wiki nowadays, thanks to wikipedia, and the "I want to edit this thing but when I pressed edit it created a fork (what's that??) and when I pressed submit it created a pull request wtf is this? Whoa, there's a bunch of text that talks about how to build nix packages and my motivation for changing this, and build-use-sandbox, and damn, is a council of strangers now going to pass judgment on my wording? Fuck this, I was just trying to help" reaction doesn't seem that implausible to me. Perhaps I hang out with a different crowd 😄

[garbas]

Anybody can have the opinion, but I don't see anybody stepping up and volunteering to do the work, which is what is needed in either case. Wiki or GH PR based approach needs somebody to do it.

Here is my suggestion if you want to do something:

1. Take tickets from "Move the wiki!" milestone that fit into manual
2. If tickets from the above milestone are hardware specific move them to nixos-hardware
3. If they fit into guides etc... create a guide or contribute to some guide (preferably to nix-cookbook)

Of course, above is my advice and what I am personally trying to do when I have free time (still stuck with nr. 1).

[vcunat]

We might leave some "free-to-edit" wiki, if you like, and whenever someone feels that a topic is good content, do a PR+review and move it to the "official docs".

Some details – we should (in case we agree to do this):

• leave some banner that the content isn't reviewed and users should search the official docs first,
• choose some spam-resistant and easy-to-use engine (maybe GitHub),
• tweak the wiki license so that it's legally clean to move content to the docs.

[FRidh]

Anybody can have the opinion, but I don't see anybody stepping up and volunteering to do the work

There's a lot of people that say they want to contribute, and I believe many will. But setting up repo's/wiki's outside the NixOS organization is a waste of effort because they don't get any traction. If we get a repo in the NixOS org to work on this I am willing to push it forward.

[vcunat]

Last time when we discussed that writing docbook is difficult, I offered that anyone can write good content in any reasonable format, ping me, and I would convert it and add to the manual. So far only Shea did so, a few times, so I don't expect a big rush, but still – my point is (again) to remove opportunities for such excuses ;-) (Just the bikeshedding has a potential to eat lots of energy that could be used for better things around here.)

[jackrsteiner]

Hi, I'm a lurker here, but I just wanted to add my two cents. I'm not sure who the target audience is for the wiki but this is the central issue. Either way, I'd argue that wikimedia wiki's are anything but intuitive. Certainly, they aren't more intuitive than github web interface. I've managed a wiki for a small non-tech organization and people do not intuitively understand its non-hierarchical structure. Its very easy for information to be hard to find and misplaced, especially if no one is actively facilitating their management. Maybe the intended audience is very familiar with how wikimedia works, but github seems the de facto standard of collaboration (more so than wikimedia). Additionally, and I know this is opinionated, but wouldn't it be good if the wiki workflow were similar to that of contributing to other nix projects, so it also functions to build capacity for new people to contribute to the main work of nix. Specifically, a github wiki contribution helps teach the workflow for contributing to nixos.

[grahamc]

!m @jackrsteiner (that's a "good work!" Thing from the irc channel, ie: great points. Thank you for coming out of the shadows to post this.) On Sat, Feb 11, 2017 at 7:18 PM jackrsteiner notifications@github.com wrote:

Hi, I'm a lurker here, but I just wanted to add my two cents. I'm not sure who the target audience is for the wiki but this is the central issue. Either way, I'd argue that wikimedia wiki's are anything but intuitive. Certainly, they aren't more intuitive than github web interface. I've managed a wiki for a small non-tech organization and people do not intuitively understand its non-hierarchical structure. Its very easy for information to be hard to find and misplaced, especially if no one is actively facilitating their management. Maybe the intended audience is very familiar with how wikimedia works, but github seems the de facto standard of collaboration (more so than wikimedia). Additionally, and I know this is opinionated, but wouldn't it be good if the wiki workflow were similar to that of contributing to other nix projects, so it also functions to build capacity for new people to contribute to the main work of nix. Specifically, a github wiki contribution helps teach the workflow for contributing to nixos.

— 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-279186139, or mute the thread https://github.com/notifications/unsubscribe-auth/AAErrHuUncGKxJKEmr5tnVCrXXc5nxe7ks5rbk_HgaJpZM4L8pBB .

[spiderbit]

I recently on the mailinglist also very loudly ranted and part of the problem was / is the state of the nixos documention which I am not very satisfied. its easy enough to do the most basic stuff but if you want to do a bit more its very hard to get the information.

I am critical to use github as nearly single point of failure, didnt you have some problems with some hosting stuff in recent weeks?

There was loss of data in gitlab a week ago or so. Do you really want to commit to github so much. Of course thats a question of scale the smaller the project the better are 3rd party host solutions, but how much does that concept scale?

Yes nixos is a niche of a niche of a niche today, but I think it could play on the same level than lets say arch linux.

You have some great package availibility that goes in some cases further than AUR (the only os I found so far, where I can install exwm and be startable through a loginmanager), the features like reverting and declaritive / reproducable systems is a bonus on top of that, it would be a great distro even without that features.

So to make it short, I could see a big future of nixos coming. Even Archlinux main installer does not shock most linux users, there are even 3rd party forks/projects that make full graphical installers and some different default packages.

All that could happen with nixos too. deb and rpm and co are kind of ruins from the past, people will switch to snaps and co, and maybe nix and guix as package managers...

So I dont think that github wiki scales enough not from a standpoint of guaranteed availability and single poind of failure nor from a optical viewpoint.

So I think the mediawiki aproach is the better one.

[vcunat]

Github wiki is a simple git repo underneath; I don't think there's anything really binding us if we use it, as the content can be easily backed up and migrated to something else.

[FRidh]

Note that the GitHub provided wiki will be open for anyone with a GH account, and PR's on this kind of wiki are not possible.

[veprbl]

I wanted to see if there were any examples of success stories with github wikis. Turns out github has a page just for this where they list their personal picks: Projects with great wikis. After looking at those I started to think that github has a somewhat different idea about what wiki's are compared to what is normally expected from a MediaWiki-based project. Majority of the wiki there are essentially presenting the main documentation for its respective software, with little to no cookbooks/hacks/gory details. The wiki engine at github seems to encourage that by enforcing a flat structure with a global table of contents, so there is no room for separate isles like topic-specific portals. I have some experience with MediaWiki and I can see how it can come out ugly at times, but at the same time I, personally, can't see a benefit of the github wiki engine that could warrant an effort consuming migration.

[expipiplus1]

I agree with @veprbl; the GitHub built in wiki is not a great fit for what wants to be accomplished here.

I had in mind something similar to @domenkozar's nix-cookbook. Each page even has an "Edit on GitHub" link at the top. There's probably nothing fundamentally challenging about getting unauthenticated on-site edits à la mediawiki on a site like that too if that's deemed necessary.

On a slight tangent, I wonder how easy it would be to get some automated testing of examples on a wiki. This might go part way towards addressing @copumpkin's, very valid, concerns about wiki maintenance. For example there could be a page about downgrading the DB schema in case of accidental upgrade, with some metadata which sets up a VM with a too-high schema version and the code on the wiki page is run and the correct schema version is verified. We have the perfect language for specifying these kinds of tests too!

Obviously this won't be applicable to many (most?) pages, but could be very handy for those willing to put the effort. Certainly this shouldn't be a requirement for adding content to the Wiki!

[vcunat]

Hmm, yes, readthedocs (+sphinx) might be good for this. If sphinx supported docbook input, we would probably use it for the "official" manuals already.

[edolstra]

By far the easiest thing to do is revive the existing wiki with GitHub OAuth to prevent spam. All the other proposals are either not wikis at all (since they require users to go through a PR process), or would create a new wiki. The latter wouldn't help with the issue of all those Google searches that point to the outdated existing wiki, unless we convert and redirect it entirely, which sounds like a lot of work.

[garbas]

Another option is also to shut down the wiki. Eventually, those wiki pages will not be indexed by google anymore. If our problem is what google thinks it is relevant then best it is to shut it down (content of wiki pages will still be accessible thru wayback machine).

In case we enable the wiki then somebody will have to step up and fix the content. Which is what we have currently a problem with anyway.

The easiest way to avoid doing documentation is to open a wiki (or a place where there is no clear guide how to contribute) and to put all the work of writing the documentation on your audience. Imagine if your school would be a wiki, where you are expected to write your own books :) great way to do a checkbox at a documentation, but not so great way to teach somebody something.

@edolstra In case editing is again possible on the wiki I guess it would make sense to close all those issues from "Move the wiki!" milestone.

[edolstra]

Hm, @grahamc added a robots.txt exclusion for indexing the wiki, but it looks like I forgot to redeploy the server with that change... I've done that now.

@garbas Yeah, I agree that's a major risk in re-enabling the wiki. OTOH, we don't have to advertise the wiki prominently. IIRC, it used to be linked from the nixos.org navbar, which endorsed it as a major place for documentation...

Regarding the "move the wiki" milestone, it's obviously still a good idea to move good content that belongs in the manual to the manual.

[vcunat]

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.)

[copumpkin]

If we go for unlocking the wiki, https://github.com/LosFuzzys/MediaWiki-OAuth2-Github looks like what we might want.

[bjornfor]

On Feb 13, 2017 12:33, "Vladimír Čunát" notifications@github.com wrote:

Hmm, yes, readthedocs (+sphinx) might be good for this. If sphinx supported docbook input, we would probably use it for the "official" manuals already.

I believe asciidoc is a more docbook friendly alternative. It can be a docbook front-end.