Quoting Matthias Beyer (2015-11-18 14:23:41) > On 18-11-2015 08:29:52, Karsten Gebbert wrote: > > IMHO, the Github wiki should probably be that place, and the workflow > > markdown/rst/org -> pandoc -> pdf/html (& possibly gh-pages). It makes it > > easy > > to contribute via $EDITOR + git or a convenient web interface. > > > > My $0.02 :) > > > > I'd vote against github wiki. It is just a mess IMHO and is for taking > notes, not for documentation. > > Though I'd vote for a markdown/rst -> git+pandoc -> html/pdf solution > (not org, as this is [kindof] bound to an editor). I'd be happy > with pandoc, but I'd vote against gitit, btw! I find it too bulkyish > and I'd prefer github as web UI, but this is debatable as well. > > Maybe we can have a sprint at 32C3 for this. > > I see one problem: The documentation is not located near to the code > it documents. We should include the documentation (as .md or .rst > files) within the nixpkgs repository and compile it with pandoc from > tree to html/pdf. > > Maybe we can set something up right now? I think I can put some effort > into this at the weekend and get something basic working, shouldn't be > too much to do, actually. >
Hi, Just to clarify to not introduce confusion about my talk from NixCon. - wiki will not go away any time soon. definetly not before we have some alternative documentation i was talking about. - tools which we use dont matter. instead of spending time on figuring out which format to choose and which framework to use to generate docs, rather write a tutorial about something. we need more content and not more tools. at least that is how i see the problem. i would much rather see a discussion what to write and not how to write. -- Rok Garbas - http://www.garbas.si
signature.asc
Description: signature
_______________________________________________ nix-dev mailing list [email protected] http://lists.science.uu.nl/mailman/listinfo/nix-dev
