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. :-)
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?
This is just for starters.
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
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
PURCHASE STYLUS STUDIO ONLINE TODAY!
Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!
Download The World's Best XML IDE!
Accelerate XML development with our award-winning XML IDE - Download a free trial today!
Subscribe in XML format