CF Conf Central
August 30th - September 1st, 2003
Las Vegas, NV



Each week from now until the Fusebox conference (Aug 31 - Sep 1), we're talking with one of the conference speakers.

WEEK 5: Jeff Peters

This week, we're talking with Jeff Peters, author of Fusebox: Developing
ColdFusion Applications, about his upcoming presentation at the
Fusebox 2003 conference (www.cfconf.org/fusebox2003).

FB: Jeff, what are you speaking on at the conference?

JP: Fusedocs.

FB: For someone who doesn't know what Fusedocs are, can you define

JP: Sure, Fusedocs are a standardized way of writing fuse
documentation. They (should) appear at the top of every fuse in a
Fusebox app.

FB: Ah, documentation is always a PITA, no?

JP: Not with Fusedocs. First, though, you should understand that
Fusedocs are not so much meant to memorialize code as to provide a
specification for that code.

FB: Hmmm...that sounds deep. What's it mean?

JP: Most documentation is written?if it's written at all!?after the fact.
That leads to a lot of worthless documentation?stuff that looks like this:

<!--- loop over products query --->
<cfoutput query="Products">
       blah blah blah

FB: I see a lot of documentation that looks like that, but you say it's
useless. Why?

JP: Maybe "useless" isn't the right way to put it. Maybe "worse than
useless" is more accurate. That comment doesn't provide any
information that a cursory glance at the code would give. That makes it
useless. The fact that it takes a coder's time makes it worse than

FB: And Fusedoc is different?

JP: Very different. Instead of having inline comments, the architect
provides a Fusedoc that tells the fuse coder everything he or she needs
to know to write the fuse. You see the difference? In the example I
gave, the "documentation" was written after the fact. In the case of
Fusedocs, the documentation is written first and forms a sort of work
order for the coder.

FB: That sounds pretty interesting. So what would the Fusedoc look like?

JP: It might look something like this:

          I display a list of products with links to buy each product.
          <history author="Jeff Peters" email="jeff@grokfusebox.com" />
               <string name="self" />
               <query name="products">
                    <string name="productID" />
                    <string name="description" />
                    <number name="price" precision="decimal" />
                    <string name="image" />
               <string name="XFA.buyProduct" />
               <string name="fuseaction" scope="formorurl" />
               <string name="productID" condition="on XFA.buyProduct" />

FB: Wow, that's a lot of info?and it's all in XML.

JP: Yes, but imagine that you are the fuse coder and you get this
Fusedoc atop a prototype page that lists all the products for sale. What
would the Fusedoc tell you? It says that the purpose of the fuse is to
list products and link them for a sale. It says who wrote the fuse and
how to contact them. It says that you, the fuse coder, will receive a
string named "self", a query named "products" (with four columns), and
an XFA named "buyProduct". And it says you should send out of the
fuse a variable called "fuseaction" and?in the case where the XFA is
buyProduct?you should send out a "productID". That's really all you
need to know. Wouldn't that be nice to have?

FB: It's a lot better than trying to guess what variables are available
and what ones I should?and should NOT?set, yes. And you said the
architect writes this?

JP: Yes, a typical Fusebox project can be broken into pieces that can
be handled by different people. The most critical person is the architect.
It's their job to make sure that all the little pieces work together to
produce the application. And that means that it is NOT the coder's
responsibility: they just have to follow the Fusedoc.

FB: Well, does it work?

JP: I'm tempted to ask a question about members of the Ursus family
and their behavior in the great outdoors.

FB: OK, but what about all that code? And all XML? Do all architects
have to become fluent in XML?

JP: Not really. They just have to learn the available Fusedoc tags. And
the good news is that there are tag extensions for Dreamweaver,
Homesite, and Studio that make that a snap.

FB: How do you know when to use which Fusedoc elements?

JP: Well, I'll be talking about that, but there's a DTD available at
halhelms.com. That's strictly optional, for those of us who like seeing
things like DTDs. It's really pretty easy to learn and to use. And the
benefits are enormous.

FB: What sort of benefits?

JP: Well, for one thing, it solves a major problem of deciding how to
document an application. It's documented before the first line of code is

FB: That is big.

JP: Huge. Another benefit is that it lets an application be broken into
many small pieces that coders of very different skill levels can work on.
You know the problem where you're working on a job and the boss tells
you that an intern can "help" you?

FB: Yes. That's worse than no help at all.

JP: But if you had Fusedocs, you could set the intern to building
something simple?maybe all the forms for an application.

FB: That would be fantastic. Are there any other tools for this?

JP: Sure! I built some pretty neat tools for working with Fusedocs at
grokfusebox.com and I'll be talking about a new generation of Fusedoc
tools at the conference.

FB: Thanks, Jeff. I'll be there to hear the latest.


Previous weeks:
Week 1: Ben Edwards
Week 2: Michael Smith
Week 3: John Quarto-von Tivadar
Week 4: Hal Helms

If you have any questions, contact michael@teratech.com