Hi Vladimir
Sounds great and I like it.
The other problem we have with documentation is also to track
them and to you have any idea or is this also supported by
Docbook (CVS tags etc.).
Can you create a documentation on how to "write a documentation"
(like "Docbood for Dummies").
Have fun - Andy
> -----Original Message-----
> From: Vladimir A Blagojevic [mailto:[EMAIL PROTECTED]]
> Sent: Thursday, January 11, 2001 1:37 PM
> To: [EMAIL PROTECTED]
> Subject: [jBoss-Dev] Documentation overhaul - a case for docbook
>
>
> 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
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
