Subject: Re: [xsl] xsl/xslt coding standard From: Steve Ball <Steve.Ball@xxxxxxxxx> Date: Mon, 19 Aug 2002 10:20:29 +1000 |
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
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
RE: [xsl] xsl/xslt coding standard, James Fuller | Thread | the time for XSLT to rally around X, James Fuller |
Re: [xsl] Inserting softHyphens in , J.Pietschmann | Date | Re: [xsl] xsl/xslt coding standard, Steve Ball |
Month |