As far as I can see, there is on the one side the demand of having the main site (or the whole docs) under version control and offline editable and on the other side a wiki-based solution such as confluence would make doc-bug-fixing very easy and fast... (plus the user-contributions in form of comments / wiki articles, blah, blah, you know the rest).
I just searched for "convert apt into confluence" and I found: http://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html. What about keeping the main site and/or docs in both systems? Just find a consensus about which is the main tool. For example, the docs are now written entirely in apt. If we export them to confluence on a regular basis (once a month or so), people could at least comment them, post links to wiki articles, blogs, etc., ... Releases could be uploaded into different subdirectories inside confluence and so on. It would just be a matter of organizing. If some committer thinks that confluence is the better way to write docs, he could convert the work back to apt afterwards... I think docbook, textile and others are also supported. Everyone writes how he wants to. Patches for the maven-based docs could be contributed by others and later published via export to confluence... (including pdf export for those, who want to read it offline) So I don't see why there can't be a proper consensus on one clear way to go on with the docs. Everybody can write docs in whatever form he likes to and there are tools out there that can convert into lots of other formats. You all mentioned good points on every possible solution, now lets bring the good parts together! Writing docs should be as easy as possible and writers shouldn't be constrained too much. :) Am 05.05.2010 um 23:52 schrieb Thiago H. de Paula Figueiredo: > On Wed, 05 May 2010 18:22:42 -0300, Sebastian Hennebrueder > <[email protected]> wrote: > >> Hello, > > Hi! > >> IMHO, we should by no means make the main pages being editable for every one. > > Nobody is suggesting that. The wiki solution would have two separate parts: > the official documentation, written and/or revised by committers, and the > community area. > > If an online edition solution isn't adopted, I would go for pure XHTML for > the documentation itself. I wrote a Tapestry course just using XHTML, CSS > (adapting the stylesheet described in > http://www.alistapart.com/articles/boom), PrinceXML to generate a PDF and a > little bit of XSLT to generate a table of contents, convert to other formats > and some other small tasks. I can share an HTML example and my CSS and XSLT > files if you want. > > -- > Thiago H. de Paula Figueiredo > Independent Java, Apache Tapestry 5 and Hibernate consultant, developer, and > instructor > Owner, Ars Machina Tecnologia da Informação Ltda. > http://www.arsmachina.com.br > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
