Return-Path: Delivered-To: apmail-incubator-abdera-dev-archive@locus.apache.org Received: (qmail 27336 invoked from network); 9 Aug 2007 19:15:35 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 9 Aug 2007 19:15:35 -0000 Received: (qmail 12416 invoked by uid 500); 9 Aug 2007 19:15:34 -0000 Delivered-To: apmail-incubator-abdera-dev-archive@incubator.apache.org Received: (qmail 12399 invoked by uid 500); 9 Aug 2007 19:15:34 -0000 Mailing-List: contact abdera-dev-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: abdera-dev@incubator.apache.org Delivered-To: mailing list abdera-dev@incubator.apache.org Received: (qmail 12390 invoked by uid 99); 9 Aug 2007 19:15:34 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 09 Aug 2007 12:15:34 -0700 X-ASF-Spam-Status: No, hits=1.2 required=10.0 tests=SPF_NEUTRAL X-Spam-Check-By: apache.org Received-SPF: neutral (nike.apache.org: 152.2.1.140 is neither permitted nor denied by domain of adam@clownsinmycoffee.net) Received: from [152.2.1.140] (HELO smtp.unc.edu) (152.2.1.140) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 09 Aug 2007 19:15:26 +0000 Received: from [152.2.190.32] (batmanuel.its.unc.edu [152.2.190.32]) (authenticated bits=0) by smtp.unc.edu (8.13.4/8.13.4) with ESMTP id l79JEgi1002962 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT) for ; Thu, 9 Aug 2007 15:14:43 -0400 (EDT) Message-ID: <46BB67A2.1000808@clownsinmycoffee.net> Date: Thu, 09 Aug 2007 15:14:42 -0400 From: Adam Constabaris User-Agent: Thunderbird 2.0.0.6 (X11/20070728) MIME-Version: 1.0 To: abdera-dev@incubator.apache.org Subject: Re: Writing documentation References: <7b774c950708091204i1f48fbf7w3f7dd0e678f7b700@mail.gmail.com> In-Reply-To: <7b774c950708091204i1f48fbf7w3f7dd0e678f7b700@mail.gmail.com> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Scanned-By: ITS Messaging Systems (outgoing) on 152.2.1.140 X-Virus-Checked: Checked by ClamAV on apache.org Dan Diephouse wrote: > I really like using Confluence. Its sooo much easier than using DocBook or > HTML. We've been using it for CXF quite successfully: > > http://cwiki.apache.org/CXF20DOC/index.html > http://incubator.apache.org/cxf/ > > It also makes it so anyone (i.e. users) can help write documentation with > very little work. I'm often able to tell people "just click edit" and we've > gotten some pretty good docs that way. > > YMMV :-) > Wikis are a good way to get your hands on the documentation. One of the considerations I put a great deal of weight on is how to bundle up the documents as part of the build process, and one thing that makes that easier is having all the source documents in the build tree. I'll note, before I shut myself up entirely on the issue, that you can possibly get the best of both worlds: http://moinmoin.wikiwikiweb.de/DocBook OK, that's enough outta me =) AC > - Dan > > On 8/9/07, Ugo Cei wrote: >> Suppose one wanted to write some documentation for Abdera, how would >> one proceed? >> >> To be more specific, I see we have a website in site/trunk, but >> that's just a bunch of HTML files that follow a common template by >> duplicating headers, menus and footers. Keeping those updated by hand >> is not really a maintainable option. >> >> How do you suggest that we approach the issue of maintaining docs? >> This is not a hypothetical question: as I'll be on vacation for a >> couple weeks, starting tomorrow, I was thinking of doing some badly >> needed documentation work. >> >> Ugo >> >> >> -- >> Ugo Cei >> Blog: http://agylen.com/ >> Open Source Zone: http://oszone.org/ >> Evil or Not?: http://evilornot.info/ >> Company: http://www.sourcesense.com/ >> >> >> > >