Re: xsl/xslt coding standard

Which still leaves my initial question, what exactly is it that we want
to document?  Honest question, I've not been documenting my XSLT that
much because I'm not sure what I want to say. :-)

I believe there are several different (what's the right word?)
"components" or "parts" to an XSL stylesheet, each requiring
a different kind or style of documentation.

At the top-level is the stylesheet itself.  What is the overall
purpose of the stylesheet?  What is the expected/required schema
of the source document (if any)?  What is(are) the outcome(s)
of running the stylesheet?  Is this stylesheet part of a modular
stylesheet system, and if so how does it fit into that system?

Templates may be named or unnamed (or both).  I find that
it is a bit difficult to pin down documentation requirements
for unnamed templates, but doco for named templates can be
more easily defined: what is the purpose of the template,
what are the parameters, what is the return result?

The general approach I take when writing system documentation is
to try and put myself in the shoes of an experienced engineer
who has just been assigned the task of maintaining the stylesheet
system.  This (mythical) person knows how to read and write
XSLT code - so don't document the bleeding obvious ("This is
a template that matches Foo elements" is obvious from
<xsl:template match='Foo'>).  Rather, what does that person need
to know to be able to quickly understand the structure of the
stylesheet system and how to use it effectively?  How does
this person quickly answer a question such as "The processing
of the Foo element is incorrect.  Of the twelve stylesheets
that comprise this stylesheet system, which stylesheet module
should I look in for the template that handles Foo elements?".

Just some general advice, and hopefully helps to answer the
"what are we documenting" question.

Cheers,
Steve Ball

--
Steve Ball            |   XSLT Standard Library   | Training & Seminars
Zveno Pty Ltd         |     Web Tcl Complete      |   XML XSL Schemas
http://www.zveno.com/ |      TclXML TclDOM        | Tcl, Web Development
Steve.Ball@xxxxxxxxx  +---------------------------+---------------------
Ph. +61 2 6242 4099   |   Mobile (0413) 594 462   | Fax +61 2 6242 4099