couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold
Date Tue, 14 Jun 2011 16:18:09 GMT

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
-- 




Mime
View raw message