[Nix-dev] Restructuring of the Wiki

[Alex Berg]

Thanks for the link to past discussion on this topic, Cillian. That was a
good discussion. Also, thank you, Third3ye, for contributing to the wiki
effort and raising Nix wiki awareness.

### On the Nix Wiki

A wiki is a low-barrier way to build a database of eventually consistent
and correct info. Good topics for this info includes history, design, and
purpose of entities, in addition to explaining relationships between topics.

In Nix project's case, several areas need such info - OS-management,
software building/distribution, and development environments using Nix. Our
wiki is not only for NixOS info, nor is it only for developers to document
their additions to Nix code. It's a place for seeing the big picture, of
both Nix and as it is meant to relate to other things. This includes its
relationship with ubiquitous software design problems or just to help out
our current projects.

If you want to add a page which doesn't fit in this picture, should you
forget about adding it? No. Just add it somewhere. Wiki maintainers, who
care about enforcing the wiki's design, can assimilate it by moving it to
the right place and editing it's style.

Now, having said that, do we still need to change how the wiki works? I'm
pretty happy with our wiki. We have zero spam now. We just need to complete
it's redesign, and new users should feel more confident adding content to
the skeleton. We've been playing with a new main page [1], but it's not
finished.

The OP also mentioned machine-generated pages. I'm not a fan. This implies
two different places to visit to edit the wiki, which distracts from the
wiki's purpose of a *central* place for community-maintained big-picture
info.

### On Moving the Wiki

This thread *does* include some discussion on moving the wiki, and I didn't
comment in last year's thread on that topic, so I'll do so now.

Requirements for software which enables this kind of information
compilation:

1) Easy for non-coders to contribute
2) Searchable
3) History of content, to recover lost info

Nice to have:

3) Organizable into topics
4) Software is easy to maintain
5) Content is portable

If we want to become "A GitHub Project", we can
- Use their wiki system
- Create a new Git repo called "wiki". We can edit and commit file changes
in GitHub browser UI.

I'm not a fan of becoming "A GitHub Project", because the Nix project is
bigger than just GitHub. How so? We have several other web sites which are
essential to Nix, including Hydra, online manuals, and the Nix homepage
itself. Also, fads come and go, and GitHub may be just a fad.

I *am* a fan, however, of having a file-based backend which still keeps
file history. I would *only* consider such a system if they can be
maintained entirely through a browser. It looks like these are both
features of Gitit.

[1] https://nixos.org/wiki/Main_Page_B



On Mon, May 19, 2014 at 9:29 AM, Anderson Torres <
torres.anderson.85 at gmail.com> wrote:

> About documentation itself, I find the format of famous "FreeBSD Handbook"
> (http://www.freebsd.org/doc/handbook/) very appealing. It can be used as
> a guide to our wiki or even a book on its own.
>
> Also, a thing I miss in the wiki is a 'hacking guide' inside Nixpkgs and
> Nix programming in general. I would like if some functions as callPackage,
> recurseIntoAttrs were more explained with examples or whatever.
>
>
>
>
>
>
>
> 2014-05-19 8:22 GMT-03:00 Cillian de Róiste <cillian.deroiste at gmail.com>:
>
> For reference, here's the discussion from the last time the topic of
>> changing wiki platform came up, last year:
>> http://lists.science.uu.nl/pipermail/nix-dev/2013-March/010800.html
>> _______________________________________________
>> nix-dev mailing list
>> nix-dev at lists.science.uu.nl
>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>>
>
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20140519/4eddd666/attachment.html