[Nix-dev] Fwd: Wiki is dead

[Shea Levy]

Someone (I think Vladimir?) offered to translate docs in any format 
into the necessary docbook, and has done so at least for one of my PRs. 
As long as that offer still stands and isn't overwhelming him, we can 
avoid spending time and resources switching over our format until we 
actually have evidence that people will write docs in the new format.

I suspect format is a red herring here. People don't like writing docs.

~Shea

On 2016-02-20 07:06, Freddy Rietdijk 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 [2] 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/
> [3] . 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 [1]
>
>
>
> Links:
> ------
> [1] http://lists.science.uu.nl/mailman/listinfo/nix-dev
> [2] https://github.com/FRidh/nixpkgs/tree/usersguide
> [3] http://nixpkgs.readthedocs.org/en/latest/
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev