I've given this subject some thoughts I'd like to share. They centre on two
central aspects: a possible requirement for a
general approach to standardising
XML documentation and simple XML comments vs. structured, namespace-based
comments.
...
 * XSLStyle supports DITA and DocBook. I have practically no experience
   with these document types, but from the little I know I'd say that
   in the vast majority of cases they go far beyond the requirements for
   documenting XSLT, XSD and so on.

   When generating documentation from an XSL document, one gets most of the
   information by analysing the code, so in a
comment one would add maybe some
   descriptive text, change and state information and a hyperlink here and
   there, or an image. The same probably applies to XSD.

   So I think that allowing the full set of DITA and DocBook features for
   use in comments may introduce unnecessary complexity.

Interestingly I saw the choice of DITA and
DocBook as introducing simplicity because in both
cases I use off-the-shelf stylesheets (included
in the package) that render these vocabularies to
HTML.  No need to write one's own documentation
vocabulary and then stylesheets for that vocabulary.

And I have a number of customers' stylesheets
documented with lists, graphics, tables, program
listings and other constructs that are all
sitting there ready to use in the off-the-shelf vocabularies.

   If one looks at Wiki text formatting like it's supported in Trac, one
   can do impressively much with little effort and complexity, including
   tables, images and hyperlinks, and the learning curve is flat. If more
   was needed, one could mix in XML islands as one does with HTML in Java
   comments.

The modular design of the stylesheets should
allow anyone to plug in their own documentation
vocabulary in place of DITA or DocBook.  You are
welcome to find or devise your own XML model for
documentation and integrate it into
XSLStyle.  The design should allow you to do this
without touching the XSLStyle fragments as I
believe those fragments have zero dependencies on either DITA or DocBook.

But you may find value in learning the basics of
these two vocabularies, but you can do a lot
knowing only that DocBook <para> and DITA <p>
allow you to document every aspect of the stylesheet with paragraphs of
prose.

Forgive my delay (because of OASIS deadlines in
two committees) in incorporating stylistic layers
in between XSLStyle and either DocBook or DITA
that have been requested by two active
users.  These changes will give a much flashier
presentation of the content that looks far more
visually attractive than just using the
off-the-shelf stylesheets.  Again, as I said
above, both any new vocabulary and its
stylesheets should be able to be incorporated
with zero changes to the base XSLStyle stylesheet
fragments.  I hope it won't be long before my committee work abates.

--
XSLT/XSL-FO/XQuery hands-on training - Los Angeles, USA 2009-06-08
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/s/
Training tools: Comprehensive interactive XSLT/XPath 1.0/2.0 video
Video lesson:    http://www.youtube.com/watch?v=PrNjJCh7Ppg&fmt=18
Video overview:  http://www.youtube.com/watch?v=VTiodiij6gE&fmt=18
G. Ken Holman                 mailto:gkholman@xxxxxxxxxxxxxxxxxxxx
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/s/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal