On 14 Jun 2011, at 18:13, Noah Slater wrote: > > 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:
I'd leave this part to MC as he's got this all figured out :) > 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. The first start were API docs, but we'll have tutorials and user guides coming up. I don't see why we should not ship something like a "getting started" guide (and others) along with the API docs if we choose to. >> 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. I forgot, if we would use git for version controlling the docs, we could use the GitHub infra (forks, comments, pull requests etc.) to sort all this out and then merge back into ASF git what's "stable" and license vetted. Cheers Jan --
