Re: [xsl] Diagramming XSLT

Subject: Re: [xsl] Diagramming XSLT
From: Wendell Piez <wapiez@xxxxxxxxxxxxxxxx>
Date: Tue, 08 Apr 2008 14:38:22 -0400
James,

I have lots of experience of this sort, plus I know people with similar experience, among whom this is an interesting topic for conversation, debate and war stories.

In my experience, what you are asking can be challenging, since it has to be calibrated very carefully to the level of your audience. An expert, patient and interested audience will do better than an inexpert, impatient and uninterested audience. But these qualities do not always go together. Plus, "expert" is a problem, since some audiences that believe themselves to be expert are expert in something less relevant than they think. (And this can lead to impatience.)

Even prior XSLT expertise can be a problem with people who have gotten off on the wrong foot.

Then there are mixed audiences, which are especially challenging.

My advice there is to aim at the most patient and most interested, which is often the least expert. You can speak to a "beginner" or near-beginner level without speaking down to anyone -- partly since the most expert tend to know that rebooting one's brain to "beginner" state is one of the most expert things one can do. :-) The best results come when you can connect with the beginners without leaving the experts out -- or if you like, connect with the expert audience without leaving the beginners behind. If the most expert are interested even in what you're telling the beginners, they will lead the others.

As for how to approach it, if what you're trying to get across is the processing model and the basic notion of matching templates and generating results, diagrams may actually be a hindrance, since the "flow" of the stylesheet as it matches one node and then another is going to be quite complex on anything but the most trivial and unrepresentative cases. People's brains don't recurse well past about four levels without help (even those of us who like the idea of recursion). We're much better with iteration.

On the other hand, I have had good results displaying a step-by-step debugger as it works through applying a stylesheet, such as the one that comes in oXygen. Even here, some attention has to be given to the source document, since it needs to be simple enough for transparency, but complex enough to be plausible (which is to say nearly "realistic"). Start with just a very few templates, and include copies of the built-in templates so their operation is not hidden. (This is important.)

As for static diagrams illustrating the processing model, this is tough. I've seen many, but none that don't have weaknesses to go with their strengths. (If anyone has any candidates I'd love to see them.)

The real message, however, is in the conceptual bridge between why XSLT works this way, what's it good for, why this is a strength not just something really strange, and so forth. For those purposes, good examples especially showing code can help. A short stylesheet that does a graceful job of rendering a deep and shaggy source document can tell volumes all by itself (especially to those who've already struggled with similar problems).

But again, how you build this conceptual bridge between the design of the language, and its nature as a strategic asset to managers and developers at all levels, is very sensitive to who your audience is, to their mindset, expectations and disposition.

I hope others contribute to this thread: it's interesting.

Cheers,
Wendell

At 12:14 PM 4/8/2008, you wrote:
I'm preparing a conference talk, and in part of that talk I will be
explaining the functioning of an XSL transform to an audience of mixed
XSLT expertise.  I was thinking that a flowchartish diagram would help.
I'm not looking to diagram every single template, just give a broad
overview - stuff like "the output from the "gentext" mode templates is
saved in this variable and then processed by the default-mode
templates."

Are there any good examples of this sort of XSLT diagram on the web?
Does anyone attempted this before and have any advice?

Thanks,

-James

-----
James Sulak
Electronic Publishing Developer
Jones McClure Publishing


======================================================================
Wendell Piez                            mailto:wapiez@xxxxxxxxxxxxxxxx
Mulberry Technologies, Inc.                http://www.mulberrytech.com
17 West Jefferson Street                    Direct Phone: 301/315-9635
Suite 207                                          Phone: 301/315-9631
Rockville, MD  20850                                 Fax: 301/315-8285
----------------------------------------------------------------------
  Mulberry Technologies: A Consultancy Specializing in SGML and XML
======================================================================

Current Thread