• Interview for Fusedocs for Better Code

• "Fusedocs for Better Code" interview with Hal Helms
• ******************************************************
• Michael Smith: This time we are talking with Hal Helms about his Fusebox and Frameworks-05 talk "Fusedocs for Better Code". So why should a developer come to your session Hal?
• Hal Helms: Isn't documentation a pain for most of us? It's one of those things that we know we should do, although we're not often sure exactly why, so we end up putting lame comments in our code like "loop over query" just above where we...loop over a query.
• MS: I might have been guilty of that once or twice in the distant past.
• HH: Me, too. I finally got fed up with this and asked myself, *Why* do we need documentation and *who's* going to use it? And I realized that the people who really need it are developers--the people who least want to write it.
• MS: Maybe we're reluctant because, although you've answered the "who", we still don't know the *why*. I suppose the answer would be "for maintaining code".
• HH: You're spot on, as our British friends say. Without good documentation (not the "loop over query" kind), mainaining code has to be one of the most unrewarding jobs. But what really surprised me was that I realized that I want documentation to tell me how to write the code in the first place. For creating apps, not just maintaining them.
• MS: But aren't you writing your own documentation and your own code? What could your documentation tell you that your code can't?
• HH: The documentation, at least as it's implemented in Fusedocs, acts like a work order, telling me exactly what *this* code file is supposed to do. Working at this level allows me to think through an entire application and make good decisions which then just need to be implemented in code.
• MS: But if I read the Fusedocs you did for a project, would I be able to understand them enough so that I could use them for maintaining the code?
• HH: Michael, if I've done a good job writing the Fusedocs, you should be able to use them to write the code initially. Even though you didn't write the Fusedoc. Even though you may not know exactly what the app is or how it works.
• MS: That's not your "loop over query" documentation.
• HH: No. When I was showing this to Steve Nelson, he commented "You're not documenting your code; you're coding your documentation". I think that puts it about perfectly.
• MS: I heard Sean Corfield mention Fusedocs at CFUnited recently.
• HH: Yes, Sean was relating his experience using the Fusedocs that were created by Synthis' tool, Adalon. He hadn't given much thought to Fusedocs, but thought he might as well try them, since they had been generated for him.
• MS: And he found them to be helpful?
• HH: Yes, he found what I've often said: with a good set of Fusedocs, you can code about as fast as you can type. All the important decisions have already been made and you're free to code at will.
• MS: Well, I look forward to hearing and seeing how Fusedocs can be implemented at your session.
• HH: Thanks, Michael.