Maven for documentation

[Borut Bolčina <bo...@najdi.si>]

I am evaluating Maven not only as a build tool, but as a central point 
for project documentation. Writing technical docs in DocBook seem the 
right choice, but integrating all the moving parts seems difficult. I 
would like to include docbkx-maven-plugin plugin in site generation. The 
doxia-module-docbook-simple does not work very well by first impression. 
It does not even display images (see my post doxia-module-docbook-simple).

In chapter 3.12. Creating a Web Site for your Application of Better 
Build with Maven it is stated

    Currently the most well supported formats available are:

        * The XDOC format, which is a simple XML format used widely at
          Apache.
        * The APT format, "Almost Plain Text", which is a Wiki-like
          format that allows you to write simple, structured documents
          (like this) very quickly. A full reference of the A PT Format6
          is available.
        * The FML format, which is the FAQ format. A simple XML format
          for managing FAQs.
        * The DocBook Simple format, which is a less complex version of
          the full DocBook format.

    Maven also has limited support for :

        * The Twiki format, which is a popular Wiki markup format.
        * The Confluence format, which is another popular Wiki markup
          format .
        * The DocBook format.

So far, in my experience, and also what I found at 
http://agilejava.com/blog/?p=31 the above does not hold true for 
DocBook. The doxia-module-docbook-simple has no documentation of its own 
at all 
(http://maven.apache.org/doxia/doxia-modules/doxia-module-docbook-simple/index.html). 
Maybe I didn't look at the right places.

If using docbkx-maven-plugin (http://agilejava.com/blog/?p=31),which is 
better, then I guess there is no way to have all the menus and other 
tech documentation generated by site plugin.

One of the requirements for the project documentation is to be 
printable. That is achived by formatting html site to be printer 
friendly or by converting it to PDF format, which is very well 
implemented in Apache Forrest. DocBook can be turned into PDF, that is 
why I think it is the most suitable (for us) format.

So, the ideal would be the doxia site plugin implementing DocBook Simple 
(or docbkx with menus or somehow integrated) with Forrest functionality 
of generating PDF directly from web page (or on demand from command line).

I would like to hear your oppinions, experience with documentation and 
any future plans.

Somehow related is also this article 
http://www.oreillynet.com/onjava/blog/2006/03/maven_project_info_reports_con.html 
from Timothy M. O'Brien.

Thanks for your input!
Borut