[Nix-dev] Fwd: Wiki is dead

Sat Feb 20 16:16:12 CET 2016

That's exactly why the wiki is good. The contribution barrier is fairly low
and you can do things without having to ask for permission.
It's very easy for anyone to come along and fix typos. Having the change
appear directly is also much more rewarding than having to file a PR and
then potentially have people bikeshed about what you did. Edit, change,
submit. Done.

For me the wiki is a good staging area where people can collect
information. The content is not necessarily very well structured and can be
outdated. Once we have good chunks of documentation we can always port them
to the manuals or guides (which are also good to have but are a different
subject).

The only thing is that since anyone can make changes, we need a couple of
maintainers that keep a friendly but watchful eye on the wiki and adjust as
needed. Instead of checking things upfront we would be checking things
after they are happening. For this we subscribe to the change feed.

On Sat, 20 Feb 2016 at 13:54 Freddy Rietdijk <freddyrietdijk at fridh.nl>
wrote:

> Adding documentation is one thing, maintaining it is a second. It's great
> if someone is willing to convert contributions to Docbook, and I'm thankful
> for that. However, that does not help much if you want to modify parts of
> it. And as Nixpkgs is updated, so should the documentation.
>
> I agree writing docs isn't peoples favorite activity, but somehow, when I
> see the amount of content that's on the Wiki, I do wonder: how come people
> chose to put it there instead of in the manual? Was it because there never
> really was a manual where the contents would fit in? Or was it because it
> was more convenient to contribute to the wiki instead of the manual?
> I haven't been around long enough with this project, so I don't know. Some
> of you will have a better idea.
>
> Being able to convert to Docbook like is done with the Haskell guide makes
> it easier for others to contribute, at least, if you know how that
> conversion is done.
>
> Some time ago I began using Nix because I like it. Python packaging is a
> mess as Domen explained during NixCon, but with Nix it works much better.
> I've contributed Python packages, and now I would like to share how it is
> done. As acoustician/researcher my work activities are quite different from
> I bet most other Nix users. Learning Nix was a big investment, but is I
> think worth it. Learning Docbook on the other hand...
>
> If you want to scare away contributors by keeping the barrier high, then
> keep the documentation the way it is.
>
>
>
> On Sat, Feb 20, 2016 at 2:04 PM, Thomas Hunger <tehunger at gmail.com> wrote:
>
>> I'm tool agnostic but +1 on having a cookbook in git for the
>> review-workflow (avoids wiki spam). I have a number of snippets (how to
>> remove gc roots, haskell profiling, how to use ihaskell properly, many
>> more) but no good place to put them.
>>
>> I've started a git-book thing [1] a while back to collect these but
>> didn't get very far. I'd much rather contribute to a common,
>> low-barrier-to-entry repository than rolling my own.
>>
>> In my experience just providing the structure will eventually attract
>> content because adding a small snippet is the path of least resistance for
>> each individual contributor. Maybe we could add a banner "This is how you
>> add a snippet" and buttons "File a bug that this is wrong / outdated" to
>> each snippet?
>>
>> Rok - I know it's not free software but maybe it's worth setting up a
>> google docs spreadsheet for coordinating the migration once we've settled
>> on a tool? I will contribute.
>>
>> ~
>>
>> [1]
>> https://github.com/WeAreWizards/nixbyexample
>>
>> On 20 February 2016 at 12:06, Freddy Rietdijk <freddyrietdijk at fridh.nl>
>> wrote:
>>
>>> 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
>>>>
>>>>
>>>
>>> _______________________________________________
>>> 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/20160220/ab5e13a1/attachment-0001.html 