Re: [xsl] XSLT documentation

Subject: Re: [xsl] XSLT documentation
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Thu, 24 Dec 2009 15:36:41 -0500
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:


http://www.CraneSoftwrights.com/resources/#xslstyle

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

Current Thread