[Nix-dev] Fwd: Wiki is dead

[Thomas Hunger]

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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20160220/a2b54fb2/attachment-0001.html