abdera-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Adam Constabaris <a...@clownsinmycoffee.net>
Subject Re: Writing documentation
Date Thu, 09 Aug 2007 19:14:42 GMT
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:


OK, that's enough outta me =)


> - Dan
> On 8/9/07, Ugo Cei <ugo.cei@gmail.com> 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/

View raw message