Hey Keith, ... i don't use fusedocs as much as I would like... but on my next project starting in a month, i have committed to doing so...
I have found that architecting is as much fun as coding... especially when you reap the benefits (time and $$) of having planned properly... obviously you will never capture every detail, but the 5-10% swing is usually easier to deal with because application is planned properly... I think the hardest part about it is not the activity itself but being convicted that it is the right thing to do and making your client understand that it is a critical part of the process... I like to say to them in not these exact words: "you will either pay for it now or pay for it later..." and clients seem to get it when I back that up with stats on how bug fixing and maintenance often cost more than the application itself in the long-term (see Code Complete for a good reliable reference to provide them)... if the application is not planned properly... A good project might look like this: *Architecting/Design --> 60% *Coding/Degugging --> 25% *Testing/Launch/Maintenance --> 15% A not-so-good (but more typical) project might look like this: *Architecting/Design --> 0-10% *Coding/Degugging --> 65% *Testing/Launch/Maintenance --> ......% (<--- oh yes.. this is where the curtomer really pays for the lack of planning) So back to fusedocs... just a tool to help in the planning/architecture... only good to use if you believe in planning and detaiuled architecture in the first place. Kyle hal helms wrote: > 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 ==^================================================================
