Can we undeprecate/unlock the wiki? #22599
Comments
|
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 ;) |
|
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. |
|
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
<#22599 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AFrc9px3Dnr3WRqvYw-XQKU3dD4KJ3KTks5ra8DtgaJpZM4L8pBB>
.
|
|
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. |
|
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. |
|
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. |
|
@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 |
To prove my point :) |
|
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. |
|
@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. |
|
Example of a cookbook that works: http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/ |
|
With "world-writable" I meant editable by anyone with a GitHub account. |
|
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. |
|
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). |
|
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. |
|
I guess if we have a PR-based Cookbook, its pending PRs would develop a useful life of its own… |
|
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. |
So have dozens of other projects that seem to get it working just fine. My main concern is for optics and practicality.
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. |
|
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. |
|
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. |
|
@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. |
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. |
|
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. |
|
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:
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. |
|
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... |
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.
Absolutely.
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. |
|
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. |
|
@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 @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. |
|
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… |
|
Wow. As an observer I would say this is clearly bikeshedding. Lets make this clear, there was only one problem with the wiki: a lot of spam. Two viable solutions where proposed: 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. 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? I really like ideas behind this project and wiling to stay for a while. Hope this helps. |
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. |
|
@vcunat I think that could be figured out later, after wiki is up and running back again. |
|
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). |
|
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:
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. |
|
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. |
|
See NixOS/infra#30. |
|
Sorry, I forgot about this stuff. I'll try to pick up where @cillianderoiste this weekend. |
|
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. |
|
… On Tue, May 9, 2017 at 6:57 PM, Drew Hess ***@***.***> 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
<#22599 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAHtgzCk6168kscl9GihYUtpZskpp5Imks5r4JrigaJpZM4L8pBB>
.
|
|
If that's really your answer, the least the project could have done is replace wiki URLs with redirects to archive.org. |
|
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). |
|
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. |
|
I've created a new issue for the ARM documentation, specifically: |
|
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. |
|
@grahamc Thanks for your measured and quick response. |
|
The fail2ban wiki had spam problems too: https://www.fail2ban.org/wiki/index.php/Main_Page
Seems like a really easy, pragmatic solution. Any thoughts? |
|
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 |
|
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. |
|
@Eisfreak7 feel free to contribute to our wiki: https://github.com/nixos-users/wiki/wiki |
|
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. |
|
@benley the stage is yours: https://github.com/NixOS/nixos-homepage/blob/master/nixos/wiki.html |
|
We now migrated all content to https://nixos.wiki/wiki/Main_Page |
|
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? |
|
It wouldn't be possible to migrate the full mediawiki history, would it? |
|
@Ericson2314 we only import the content itself. |
and others
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:
cc @edolstra @domenkozar @garbas @grahamc
The text was updated successfully, but these errors were encountered: