+1 for docs in the same place as the code. One of the main reasons is that a single commit adds the feature, the tests that confirm the feature works, and the doc changes that let folks know about it. It's just sane.
And -1 on keeping them floating around externally and sucking them in somehow at release time. B. On 14 June 2011 17:48, Jan Lehnardt <[email protected]> wrote: > > On 14 Jun 2011, at 18:45, Jens Rantil wrote: > >> Just throwing in my 2 cents in this discussion. >> >> On Jun 14, 2011, at 6:13 PM, Noah Slater wrote: >> >> /doc >> /doc/docbook >> /doc/docbook/root.xml >> /doc/docbook/ch1.xml >> /doc/docbook/ch2.xml >> /doc/docbook/ch3.xml >> /doc/Makefile.am >> >> You get the idea. The Makefile.am would contain a bunch of rules that would >> allow us to convert this DocBook into plain text, DocBook, man, info, LaTeX, >> PostScript, and PDF as needed. All very straight forward. >> >> Is really writing documentation XML the best we can come up with? How about >> using 'pandoc' (http://johnmacfarlane.net/pandoc/) to write documentation in >> restructuredText, markdown or textile instead? They are all way easier to >> read and write for newcomers. > > They are also not capable of structuring documentation exhaustively. I hate > XML as much as the next guy, but MC's doc system is really slick and not as > bad once the basic infrastructure is in place (I'll show it soon, promised). > > Cheers > Jan > -- > > > >
