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 <[email protected]> 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 > [email protected] > http://lists.science.uu.nl/mailman/listinfo/nix-dev > >
_______________________________________________ nix-dev mailing list [email protected] http://lists.science.uu.nl/mailman/listinfo/nix-dev
