From dev-return-16658-apmail-couchdb-dev-archive=couchdb.apache.org@couchdb.apache.org Tue Jun 14 16:18:39 2011 Return-Path: X-Original-To: apmail-couchdb-dev-archive@www.apache.org Delivered-To: apmail-couchdb-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id BDB276BCD for ; Tue, 14 Jun 2011 16:18:39 +0000 (UTC) Received: (qmail 31307 invoked by uid 500); 14 Jun 2011 16:18:39 -0000 Delivered-To: apmail-couchdb-dev-archive@couchdb.apache.org Received: (qmail 31268 invoked by uid 500); 14 Jun 2011 16:18:39 -0000 Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list dev@couchdb.apache.org Received: (qmail 31260 invoked by uid 99); 14 Jun 2011 16:18:39 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 14 Jun 2011 16:18:39 +0000 X-ASF-Spam-Status: No, hits=0.7 required=5.0 tests=SPF_NEUTRAL X-Spam-Check-By: apache.org Received-SPF: neutral (athena.apache.org: local policy) Received: from [80.244.253.218] (HELO mail.traeumt.net) (80.244.253.218) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 14 Jun 2011 16:18:31 +0000 Received: from dahlia.local (p5797A2B8.dip.t-dialin.net [87.151.162.184]) (using TLSv1 with cipher AES128-SHA (128/128 bits)) (No client certificate requested) by mail.traeumt.net (Postfix) with ESMTPSA id 5CB3C3C353 for ; Tue, 14 Jun 2011 18:18:10 +0200 (CEST) Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Apple Message framework v1084) Subject: Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold From: Jan Lehnardt In-Reply-To: Date: Tue, 14 Jun 2011 18:18:09 +0200 Content-Transfer-Encoding: quoted-printable Message-Id: <9AAB7C41-34B8-4252-B623-B88C8C3F97D3@apache.org> References: <20110613070433.1622.84988@eos.apache.org> <02E53EA0-4601-437F-9B18-72A74803D712@apache.org> To: dev@couchdb.apache.org X-Mailer: Apple Mail (2.1084) On 14 Jun 2011, at 18:13, Noah Slater wrote: >=20 > On 14 Jun 2011, at 15:54, Paul Davis wrote: >=20 >> 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. >=20 > Thanks, Paul. :) >=20 > 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. >=20 > 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. >=20 > 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 --=20