[Nix-dev] Fwd: Wiki is dead

[Freddy Rietdijk]

I agree with Vladimir that we already have the infrastructure, the Nixpkgs
repository.

What is needed is a clearer way where to put certain documentation and a
lower barrier for contributing. In `Redesign of documentation` I came with
a proposal of how to structure the documentation. A wiki has a low barrier
for contributing, however, it also has many disadvantages, which you would
not have if we use, say, the Nixpkgs repository.

A big barrier, in my opinion and I'm pretty sure also in that of others, is
the current format of the Nixpkgs manual. I can understand why docbook is
used, and I think it should be used for say the Nix manual, but for a
User's Guide to which many of us would/should contribute, the barrier is
just too high.

On the branch https://github.com/FRidh/nixpkgs/tree/usersguide I
implemented the proposed redesign.
The documentation is split into two documents, the User's Guide, and the
Contributor's Guide. The User's Guide is divided into three parts:

   - Introduction
   - Reference
   - Cookbook

There have been several proposals already for tools/implementations
(Matthias' Jekyll implementation, Domens Sphinx docs) . Here I chose to go
also for the Sphinx documentation generator. It allows you to write
RestructuredText. With a small plugin, which I enabled, you can also
include CommonMark/Markdown. Nix highlighting is supported.
The result can be found at http://nixpkgs.readthedocs.org/en/latest/ . It's
mostly empty still.

Now this is only a proposal, and I'm open to other ways. But I really think
we should do something about the current state of the docs, in both content
and lowering the barrier. ReStructuredText/Markdown obviously doesn't have
as much possibilities as Docbook but what matters eventually is whether it
is enough, and I think it will be, at least for now.


On Sat, Feb 20, 2016 at 12:30 PM, Vladimír Čunát <vcunat at gmail.com> wrote:

> On 02/20/2016 12:52 AM, zimbatm wrote:
> > It's a great staging area for content where people can edit without
> > asking for permission. [...]
>
> What are the advantages in comparison to standard pull requests with
> discussion underneath? We already have lots of infrastructure advantages
> in there, such as merging changes at once with documentation for them,
> auto-mention bot, etc.
>
>
>
> _______________________________________________
> 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/20160220/7034a418/attachment.html