Keith, Just throwing in my 2 cents here. The problem you're describing is a common one. The reason for it is that the architecture hasn't been sufficiently thought through before you begin to either Fusedoc or code. Fusedocs document what you have planned, but if the planning isn't sufficient, you'll find this out when you start writing your code. In that case, a decision NOT to write Fusedocs is entirely rational.
Architecting an application - especially a large or complex one - is hard work and sometimes frustrating work. There is *nothing* fun about throwing away 6 hours of work because my architecting shows me that an earlier decision will run into a dead end. Still, it's a lot better than finding this out when coding. My experience has been that many of us developers don't spend much time in architecting an application and that decision leads to a lot of problems further down the line. I've had this experience in another area: when I first start doing technical writing, I did magazine articles. I found that I didn't need any real planning on these; I just wrote them. When I wrote the first book, though, I ran into HUGE problems due to my lack of planning. I would get to page 238 and wonder, "Did I already say this?". I rewrote the book 4 complete times. What a mess! Finally, someone said to me, "You need to architect a book, just like you architect an application." The thing is architecting a book didn't feel natural to me. In fact, I really did not like it. I felt I would be constricted in the actual writing by decisions I made in planning. It really was uncomfortable, but I stuck with it because I didn't like the results of NOT architecting the book. Gradually, it got easier and my fears diminished. I found that, quite apart from my worries, having a detailed outline gave me a system into which I could put my thoughts. Now, I'm actually starting to like architecting books and I *love* architecting applications. -----Original Message----- From: Keith Young [mailto:[EMAIL PROTECTED]] Sent: Friday, May 24, 2002 8:53 AM To: [EMAIL PROTECTED] Subject: Re: Who Uses Fusedocs? Steve, I will confess to not using Fusedocs the way they are meant, but I have always wondered, do you find you have to go modify the fusedocs you pre-wrote for an application very often? For example, the application I am working on right now, I started with one method of passing variables around from page to page. Then proceeded to a second method, and finally a third (which I now believe is the best way for the complexity of the forms I am using). If I pre-wrote the fusedocs I would at best have to modify it once to match my final method of handling, and in a worst case I would modify it every time thinking that "this time" I am doing it the best way. Perhaps my perspective is merely one of not having years of dynamic web development behind me? That as time goes on I would find the need to go back and redo whole sections/pages of code to be better would lessen, and therefore I could approach the "write the doc, code the doc" (once), levels of achievement? I have stayed away from fusedocing because I know that I will go back through my code several times and it will end up potentially different, or I may have completely overlooked a component I needed and have to add it in later. I'm not sure what the answer to my ponderings above should be... I *know* I would like to "code the doc", but I am not sure if it of large benefit when I go back and rewrite code alot to be better... Cheers, Keith. >>> [EMAIL PROTECTED] 05/23/02 09:43pm >>> Rey Muradaz wrote: > > Yes, but that info would be pretty helpful if you're trying to add on > another floor, don't you think? (BTW, I hope you're not saying that > all of your development projects end up in a heap of wreckage . . . > :). > Maybe, maybe not. I've tried this two ways and they both seem to work about the same, but for different reasons. I've tried one way where I make changes to the prototype, then use the existing fusedoc to modify the new one. I've also tried, making changes to the prototype, scraping the old fusedoc and refusedocing the changed pages in the new prototype. I guess it has to do with how much you're changing in each fuse. If you're changing a lot, that old blueprint will just slow you down. Here's an analogy. My mother has been a home renovation architect for 30 years. If the house she's working on will be ripping off the roof to put on another floor, having the blueprints for that roof won't do her any good. She just needs measurements to create the new blueprints. The NEW blueprints get submitted to the engieers for structural review and the builders to build the new floor, not the old ones. > Documenting up front is the best, but documentation at *any* point in > the process is still useful when you have to pick up someone else's > work weeks, months or (yikes!) years later. I'd say it fully depends on the type of documentation you get. Stupid documentation does you nothing regardless of when it's written, like this: <!--- loop over query ---> <cfloop query="somequery"> or <!--- setting first_name variable ---> <cfset first_name="Steve"> That just won't do you any good. Now Fusedocs documentation at any point in the process... it might help it might not. I'd still start with the wireframe, go to the prototype, fusedoc, fusecode and unit test, regardless of how much was already built and working. If *some* of the fusedocs were already written, then great, it helped. If you added new stuff, new fusedocs would need to be written. btw, as far as wreckages go. Sure, i've had my share of wreckages, and my share of successes. My biggest flop crashed 2 weeks before we were going to sign a contract for $26,000,000 (that's a lot of zeros!!). That was the day I began to really take Fusebox seriously. Steve Nelson > > REM O- > > >>> [EMAIL PROTECTED] 05/23/02 12:36PM >>> > Is it? Knowing how much weight a steel beam can hold seems pretty > pointless to me.... if the building has already collapsed. > > Steve Nelson > > "Benjamin S. Rogers" wrote: > > > > > Steve is right; documenting post-development is pointless; > > > Fusedocing up front is powerful. > > > > Pointless? That's a bit extreme, isn't it? > > > > Benjamin S. Rogers > > http://www.c4.net/ > > v.508.240.0051 > > f.508.240.0057 > > ==^================================================================ This email was sent to: [email protected] EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrFMa.bV0Kx9 Or send an email to: [EMAIL PROTECTED] T O P I C A -- Register now to manage your mail! http://www.topica.com/partner/tag02/register ==^================================================================
