[Nix-dev] NixOS-Wiki alternative. Was: What license does the content of the nixos wiki and the manuals have?
Eric Sagnes
eric.sagnes at gmail.com
Sat Sep 26 02:04:57 CEST 2015
Hi,
A few considerations:
I would be great to have support for i18n, including guidelines and
workflows for foreign languages. (eg: Who with merging privileges can
determine if a contribution in thai is not spam?)
Git and command line can be a big hurdle for non technical users, so to
help them there should be a beginner tutorial on how to contribute
and an alternative way to submit content (for example in an
issue with a dedicated label)
PRs are great for big commits but they can brings more friction for minor
changes like grammar or typo fixes.
And specially if the number of pages get big it can means a large number
of 1~10 characters change PR. (Using issues for minor edits could be a
solution)
Cheers,
On Fri, Sep 25, 2015 at 02:24:56PM +0200, Matthias Beyer wrote:
> On 25-09-2015 12:58:14, Eelco Dolstra wrote:
> > However, an alternative to relicensing is to combine it with a move to a
> > different Wiki, which many people have wanted in the past anyway. For instance,
> > we could set up a GitHub wiki, and people could copy their own contributions to
> > the new wiki. The new wiki should of course have a license from the start.
>
> Well, if we start this discussion here:
>
> In fact, I asked the licensing question _because_ I'm working on an
> alternative wiki for nixos. The whole point of my question is that I
> want to be sure that I can use contents from the official wiki.
>
> I didn't want to ask for permission that early, so I just
> asked about the license of the wiki and docs, but well... as we are at
> that point in our discussion now...
>
> Anyhow, I strongly disagree with your proposal to use the github wiki.
> It is _far_ to complicated to keep things organized in there. Subpages
> and all this stuff.
>
> Of course, I did some investigation on the subject. I tried several
> wiki software packages.
>
> Let me elaborate:
>
> My requirements:
>
> 1. git. I want to have the content (and, if possible, all
> metainformation like page templates and so on) tracked in git.
>
> Contributions would go through git as well. So why is that? I
> can already hear voices argueing about this. Yes, it is
> a bit of an obstacle if you are only able to contribute via a
> pull-request procedure.
>
> BUT there are some big pro points:
>
> 1) Contributions are reviewed. One can't argue with that.
> People can actually review contributions before they go
> online. This keeps up the quality of the wiki and
> automatically protects it against abuse. I believe that this
> becomes more important as the wiki (or the number of people
> involved in nix{wiki, os, pkgs, }) grows.
>
> 2) Having a long(ish) running process for adding/editing
> content of the wiki keeps people from "just pasting this in
> the wiki somewhere". I believe that if there is a bit of a
> process behind all this, it keeps people from just dropping
> in content.
>
> Some more pro points which are not that major as the ones
> above:
>
> 3) git-log. You can log the history of single articles or even
> topic-trees (speaking of subdirectories). You can do the
> former with, for example, MediaWiki. But not the latter, I
> guess.
>
> 4) git-blame. You can actually see what happened where. And
> yes, you can do this wiki MediaWiki, too. But tell me:
> How often have you actually done this?
>
> Of course there are more points. Let me summarize them: git.
>
> 2. One-click contributions (not really, actually). I want user to
> be able to do contributions with only a few commandline calls.
> Idea was that a user only needs to fork the repository, edit the
> contents of some Markdown page and rebuild the wiki to review.
> One-click contributions like in a MediaWiki instance is not what
> I want, as described in 1.
>
> 3. Local clone.
> Well, git gives us the opportunity to run a _full clone_ of the
> wiki locally. You cannot do this with MediaWiki (maybe you can,
> but not _that_ easy).
>
> Okay, so here are the things I reviewed:
>
> - gitit (Haskell, integrated with nixos)
> - gollum (ruby, actually the software that powers the github wiki)
>
> These are the only options I found for a wiki with git as backend.
>
> gitit
> -----
>
> Gitit is awesome. It works great and is fast.
> Anyways, it has some issues. First, it does not track templates.
> You can write page templates, but they are not tracked in git.
> I had to do some nasty hacks for this.
>
> The templates cannot be used to generate, for example, warning
> blocks:
>
> { warning_block "Do not install this in User env" }
>
> (Just an example, not the actual markup for templates)
> The above is _not_ possible with gitit. Kinda dealbreaker for me.
>
> There are few plugins for gitit. I failed installing even
> the simplest of them using nixos tools.
>
> Also, gitit is not actively maintained. There is an attempt to
> rewrite gitit (called gitit2 actually) which is even less
> maintained.
>
> Running not-that-well-maintained software is ... problematic at
> least.
>
> gollum
> ------
>
> Powering the github wiki, relatively actively maintained... Good
> idea I thought. But:
>
> - No templates
> - No Plugins
> - Not even custom style (you can do it, but I couldn't find
> documentation about it)
>
> Also, gollum is great for single-user use. I use it locally to
> keep some notes. It works great. But I fear distributing it and
> merging around. It is just not the way it is supposed to work, I
> think.
>
> And, of course, it is rather complicated to keep track of where
> things are actually stored. You can mess up really bad (I already
> did) by just naming a _folder_ like a _file_.
>
> All in all, it did not _feel_ that good using it.
>
>
> So these were my options on wikis with git as backend. There are no
> others (well, there is a perl-thing, I didn't test this one,
> actually).
>
> Sadly, I couldn't satisfy myself with these options.
>
> So, an idea came up - why not using static pages for all of this? If you
> want to do contributions via git, you can use github. If one want to
> host it, one can use github pages and build it with travis-ci. These
> things are documented and they _work_ for other people, so why not for
> a wiki?
>
> To be able to build pages with travis-ci and github pages, one needs a
> static site compiler. I used a static site compiler which is actively
> maintained and developed and actually supported by github, because
> they use the same for github pages: Jekyll.
>
> I cannot build the page itself with github pages, because they do not
> allow plugins. But one can build with travis and push to the
> github-pages branch, there's a lot of documentation about it.
>
> Things like plugins, custom themes, templates and all this stuff are
> supported (more or less) out of the box.
>
> I started to write this as a template for a wiki and I plan to fork it
> and create a wiki for nixos out of it.
>
> Well, enough talking, here is the codebase:
>
> https://github.com/matthiasbeyer/wiki.template/tree/transform-to-jekyll
>
> (branch "transform-to-jekyll" because I actually started it with
> "nanoc", but jekyll is a much better option)
>
> The idea of the template is that one can fork it, delete the content
> which is in the wiki right now (documentation on how to use it) and
> start putting content in it. Everything else has to work out of
> the box.
>
> I used a jekyll-site template as you can see in the commit history.
>
> I'm not finished yet, some things are missing by now:
>
> - Non-Markdown pages (textile, for example) Don't know whether
> this is possible or needed.
>
> - Some plugins are included as source files, not as gems. Pull
> requests to the actual plugins are pending and I hope I can
> integrate them as gems asap.
>
> - Latex-Formulas (not tested yet). Not required for a nixos wiki,
> I think.
>
> - Style is not finished yet. I'm not a designer, though I think it
> looks rather pleasent for my limited designing skills.
>
> I'm not sure whether I want to have a discussion about it yet, but as
> Eelco mentioned quitting the old wiki and creating a new one, I had to
> post this to the mailing list.
>
> I hope we can have a calm and objective discussion about this now.
> I'm able to argue with people, but I don't like cursing, fighting or
> anything. Keep it objective, please! I'm rather confident I will do
> this, whether the nixos community agrees or not, but I would really
> love to have a collaborating atmosphere about this, so we can pull
> this together and cooperate.
>
> --
> Mit freundlichen Grüßen,
> Kind regards,
> Matthias Beyer
>
> Proudly sent with mutt.
> Happily signed with gnupg.
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
--
Eric Sagnes
サニエ エリック
More information about the nix-dev
mailing list