Re: [xsl] XSLT documentation
At 2009-12-24 15:21 -0500, Brian Newman wrote:
What are best practices for documenting XSLT?
I have a freely-available environment for documenting all of the
top-level constructs of all imported and included stylesheet
fragments, complete with an alphabetized index and enforced business
rules for writing stylesheets:
It is stylesheet scaffolding in which you use either DocBook or DITA
(or soon XHTML) within the scaffolding to add paragraphs, lists,
graphics, etc. and you can drag it onto IE to render HTML
dynamically, or use any engine to create standalone HTML documentation.
It is in the process of being updated based on valuable input from
XSLT list members (thank you Florent and Dominic!), and woefully
overdue (sorry 'bout that!). I'm hoping to find time during the
holidays to work on it.
I've tried to do it using UML, but it seems like putting a square
peg in a round hole - not a real good fit (I think because UML, at
least in my mind, is for imperative code and perhaps even more
specifically for OOP).
Have you ever been tasked to describe _graphically_ what a transform
is doing and, if so, how have you done it?
Nope ... I can't say any of my customers have requested that. Other
than the tree of imported and included stylesheet fragments, I'm not
sure what would be documented graphically. I'm not sure what my
customers would want to see graphically about a stylesheet.
I have many times documented graphically the data flow of my
customer's information through stylesheet and other steps in an
integrated solution. And, using XSLStyle, I've included these
graphical images in the documentation I deliver to my customer that
is generated from the actual stylesheet fragments. This methodology
means that my stylesheet documentation is not maintained as a
separate document (more chance to get out of date?) and is integrated
with information from all fragments.
An XSLT stylesheet is declarative ... what gets called when is
determined by the nature of the input data ... what kind of implicit
relationships are there that might be shown graphically? Perhaps the
calling of a named template? Perhaps the grouping of template rules
in a particular mode? Would such information help someone
maintaining a stylesheet do their job? When you write a stylesheet,
what graphical depictions would help you?
An important issue of rigourous stylesheet writing is that the
business rules I follow ensure that I've documented every top level
construct in every stylesheet fragment before it is delivered to the customer.
I hope this is helpful.
. . . . . . . . . . . Ken
UBL and Code List training: Copenhagen, Denmark 2010-02-08/10
XSLT/XQuery/XPath training after http://XMLPrague.cz 2010-03-15/19
XSLT/XQuery/XPath training: San Carlos, California 2010-04-26/30
Vote for your XML training: http://www.CraneSoftwrights.com/s/i/
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