Hi,
Our fellow JBoss colleague Tobias French has initiated JBoss documentation
discussions regarding different approaches to resolving our documentation
problem.
Some time ago upon "directive" from Marc I started working on JBoss container
walk-through paper (finally done now) which also kicked off my search for
documentation solution.
After some considerate time spent looking around I came to a conclusion that
Docbook XML initiative is the most reasonable way to go. DocBook is a XML
and SGML DTD that lets authors in technical groups exchange and reuse
technical information. Docbook DTD defines some 300 elements that are
contextually related to a computer technical writing.
For example DTD contains elements such as : computeroutput, programlisting,
chapter, para, article , faq etc
To get a feel of docbook-ed JBoss CMP article point your XML client here
http://www.ariel.cs.yorku.ca/~cs962267/docbook/cmp.xml
Docbook "package" comes with XSL stylesheets that allow technical groups
define different views of Docbook-ed XML content. Currently defined are
XML-HTML and XML-PDF stylesheets that allow creating of HTML and PDF documents.
These stylesheets are very flexible, well maintained, allow easily
customized hooks for specialized home-brewed styles of HTML views.
One specialized HTML view that I goofed with can be found at:
www.ariel.cs.yorku.ca/~cs962267
The point is : you have one xml content, chunked into logical pieces
(i.e articles) which are then easily arranged , put together, and in
the end XSL stylesheet is applied against it to create any kind of
HTML view or PDF or PS etc etc
DSSSL stylesheets, used in era of SGML can also be used to create
specialized views formats. In fact ,while experimenting with this on
RedHat Linux I managed to create doc, ps, dvi and all other different
kinds of formats from single docbook article.
Principal maintainer of Docbook is Norman Walsh , www.nwalsh.com ,
one of the best guys in this industry , a member of XSL working group,
Sun Microsystems employee.
Not to mention that Redhat, GNOME , KDE and all other major players
are already "on" Docbook. See a good article printed more than a year
ago at http://www.xml.com/pub/a/1999/10/docbook/docbook-making.html
I have already docbook-ed more than 50 % of our documentation.
To finish HTML part of documentation I estimate that we would need
some 2 man days to finish it, another 3 man days to nicely arrange
everything ( customized HTML view , content arranging) and finally 1 man
day to create ant build script to generate doco. After that maintaining
should be very efficient/cost-effective. Content authors don't have to
worry about content views only content. Documentation maintainer only
arranges content and maintaints stylesheets. Piece of cake , work
divided, view is consistent , everybody is happy.
In a summary I think that Docbook is the best choice to easily maintain
current documentation, update it , and create and kind of desired view
of the content.
I gladly await any other approaches, views , questions. If needed maybe
after some discussion the board can make a vote so we can close this
chapter and move forward.
Sincerely,
Vladimir
