On 14 Jun 2011, at 15:54, Paul Davis wrote: > If Noah agrees with the doc system then I'm in. I point him out > specifically because of the work I know he was responsible for on the > O'Reilly book and he had a couple iterations of how to maintain a > large amount of text with code and image inserts so AFAICT he's > probably in the best position to make a judgement of what'll be > awesome or not.
Thanks, Paul. :) If we're going to ship documentation with CouchDB, I have a good idea about how this should look. I've actually done this before on a previous Autotools based project I was developing for the GNU project itself. We would create the following directory structure: /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. The generated files would be included as part of the distribution artefact, but would not be included in the repository. This might also be a good opportunity to make that change for our man page. You realise we have a man page, right? It's just that most people don't have the tool needed to generate it, and we don't ship it by default. Which is a bug. This documentation would then be installed locally on each system that CouchDB is installed on (so that Futon can link right through to it) and we should also export it into the /site directory so that it is available via the web for people who are browsing the CouchDB site. Note, I am not sure where we want to draw the line between documentation and tutorial. An API reference with basic examples would make sense for us to ship. CouchDB TDG, on the other hand, is more tutorial based. I am not sure what kind of documentation CouchBase are working on, but I doubt we'd want to move it all to the source tree. > Except for the comments. I agree that we need to allow for super easy > contributions without a login, but comments are a blight on the > internet. Perhaps a mailto link that opens up dev@ or a form that just > emails dev@ or maybe a special docs@ list. If we're gonna work on > making our docs all pretty, the last thing we should do is give the > collective internet-as-five-year-olds group a big marker to draw all > over them. A lesson we learnt from the CouchDB book: collecting comments via email sounds sensible, but proves to be burdensome. Inline or in-page comments, or a bug tracker are both much better solutions.
