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
======================================================================