BorlandTalk.com Borland discussion newsgroups   Archives   FAQ   Search   Memberlist   Usergroups   Register   Profile   Log in to check your private messages   Log in  Design documents versus prototypes Goto page 1, 2  Next          BorlandTalk.com Forum Index -> Delphi Non-Technical View previous topic :: View next topic   Author Message Scout Guest Posted: Tue May 09, 2006 11:14 am    Post subject: Design documents versus prototypes I'm frequently given tasks by a huge corporate customer with a heterogenous IT system and more Business Analysts and consultants that you could shake a stick at (even if you were particularly adept at stick-shaking). At a project review today which covered multiple projects, the customer acknowledged that I had delivered the required code in less time than the already very tight time-frame, and that the cost was under what they had budgeted for. Then I got a bollocking for not producing design documents so that the BAs and consultants could see what they were going to get. The only thing that I could think of saying in my defense was 'I did give you the design documents, but instead of being written in Word, they were written in Delphi, they worked, and showed you precisely what you were going to get'. I had taken the requirements document and used the RAD power of Delphi to show exactly how the system would work in less time than it would have taken me to come up with a bunch of words that conveyed much less information. Since the data access layer didn't exist when I created the prototype, I used things like: procedure TMyForm.OnBarcode(sender : TObject; const Barcode : string) begin {$IFDEF FAKE} // code that responds with some hard-coded values // and shows what should happen {$ELSE} // no code here, but this is where I'll write the real stuff {$ENDIF} end; ....and put some real logic into the FAKE part so that all eventualities could be tested as long as they stuck to the hard-coded barcodes. I know that I'll never win the battle of words versus work. The Project Manager even said "This is the same problem we've had with you for the last 14 years, but you always deliver on time (or before time) and on or under budget", so she's not going to win either. What amazes me is that few corporates ever take advantage of the incredible power that Delphi provides in being able to produce working prototypes in a very short time. I also got a bollocking for refusing to commit to a delivery date. As I said, this is an heterogenous system, and when I built the prototype, the data access layer didn't exist and was provided by another party. I was happy to commit to "3 days after the data is available, you can have your Delphi system", but project managers often don't see that as a commitment. Some of the parts of the system were written in Java, others in COBOL, and the rest is Delphi. The Java part slipped under the radar 'coz none of the BAs actually understand what it does, and it seems that for COBOL stuff you really need to write documents specifying what is going on (or is planned) while the Delphi stuff just works. Don't get me wrong: if there is a need to write database design documents to illustrate how the data relationships are going to work, then I'm your man. But if the proof in the pudding is whether or not the solution is going to fulfill the requirements, then I reckon that a prototype wins hands down every time. And it seems that amongst all of the tools available to all of the people that work with these projects, only Delphi is able to produce working prototypes within the sort of timeframes that we are given. The other thing that I love about Delphi is that there's not too much trouble in turning a prototype into a working system. Yeah, we can mess about with the prototype till the cows come home, but when the customer finally agrees that the prototype does what is required, there's very little work left to do. What's your experience? Scout Back to top Eric Grange Guest Posted: Tue May 09, 2006 11:14 am    Post subject: Re: Design documents versus prototypes Quote: What's your experience? Prototypes are a bit like miniatures of a building: they can look good, be useful to give a good overall idea of the building's size and shape, but if you're going to buy an apartment in a that building, you'll be looking for more details than a pretty miniature. You'll want written words about what exactly you'll get, and what you won't. And you'll also want a delivery date and get one, even if the builder can't be sure of it (f.i. they couldn't bump on some archaeological remains, have some unforeseen trouble stabilizing the ground, etc.). Sure, you can always trust some builder on a miniature, and seal the deal with a handshake, but that requires a serious amount of trust ;) Eric Back to top Oliver Townshend Guest Posted: Tue May 09, 2006 12:14 pm    Post subject: Re: Design documents versus prototypes Quote: I'm trying to figure out exactly what a "bollocking" is. Neither I nor "dictionary.com" know. Is it kinda like a methaphorical butt-kicking? Yes, except your bollocks are on the opposite side of your body. Oliver Townshend Back to top BobW Guest Posted: Tue May 09, 2006 12:14 pm    Post subject: Re: Design documents versus prototypes I'm trying to figure out exactly what a "bollocking" is. Neither I nor "dictionary.com" know. Is it kinda like a methaphorical butt-kicking? Bob ______ "Scout" <Toothpaste (AT) farts (DOT) com> wrote in message news:MPG.1ecb3543718ad8ee989789 (AT) newsgroups (DOT) borland.com... Quote: Then I got a bollocking for not producing design documents so that the BAs and consultants could see what they were going to get. I also got a bollocking for refusing to commit to a delivery date. What's your experience? Scout Back to top Jim Cooper Guest Posted: Tue May 09, 2006 12:14 pm    Post subject: Re: Design documents versus prototypes Quote: When it comes to delivery and budget, which is better? The point here would seem to be playing nicely with others. The prototype may be all very well for you as a one man band, but it doesn't help anyone else with writing their systems that need to interface with yours. I'm in the exact same situation myself ATM, with 4 companies writing different parts of a complex system. The other people/companies need to be able to coordinate their efforts with yours. I would be mightily p!ssed off if I had to trawl through source code looking for what each one was expecting as interfaces (not meaning this in a language feature way here). Cheers, Jim Cooper _____________________________________________ Jim Cooper jcooper (AT) tabdee (DOT) ltd.uk Skype : jim.cooper Tabdee Ltd http://www.tabdee.ltd.uk TurboSync - Connecting Delphi to your Palm _____________________________________________ Back to top Scout Guest Posted: Tue May 09, 2006 12:14 pm    Post subject: Re: Design documents versus prototypes In article <446072f9$1 (AT) newsgroups (DOT) borland.com>, egrangeNO (AT) SPAMglscene (DOT) org says... Quote: What's your experience? Prototypes are a bit like miniatures of a building: they can look good, be useful to give a good overall idea of the building's size and shape, but if you're going to buy an apartment in a that building, you'll be looking for more details than a pretty miniature. You'll want written words about what exactly you'll get, and what you won't. Eric Eric, I always respect what you have to say and I kinda agree that the written words are what the customer wants. I have a love-hate relationship with this customer: love because I always deliver, hate because I don't always do it their way. When it comes to delivery and budget, which is better? do it their way (with docs galore), delivery unknown and blow the budget, or my way with guaranteed delivery (taking into account 3rd parties) and within budget? I'm sure that there are many Delphi developers in the same position as me. Do we deliver the goods or do we play the corporate game? I'm certainly not saying that I'm right. I get away with what I do because the customer always chooses something that works over something that is well documented but doesn't work. Maybe I should learn how to document my stuff better. That would nail it, but I'm getting old, tired and lazy. Your post suggests that I shouldn't be so lazy. You're right. If I put in some more effort, I could produce better prototypes, better code, better solutions and better documentation than any of my contemporaries or competitors, but for now I'm happy to live with Delphi doing most of the work for me. I guess the biggest difference between the many systems is that while there is one of me (with a Delphi compiler), there are at least 8 folks doing the COBOL stuff, and 7 BAs saying what should be done. Even with my own quirks, an 8, 7 or 15 to one ratio must make the the Delphi solution look good. No-one is ever going to hire me now. I'm too old, too opinionated and GET OFF MY LAWN. But I still get to do this stuff and Delphi is the best way to do it. Scout Back to top Scout Guest Posted: Tue May 09, 2006 12:14 pm    Post subject: Re: Design documents versus prototypes In article <4460832b$1 (AT) newsgroups (DOT) borland.com>, jcooper (AT) tabdee (DOT) ltd.uk says... Quote: When it comes to delivery and budget, which is better? The point here would seem to be playing nicely with others. The prototype may be all very well for you as a one man band, but it doesn't help anyone else with writing their systems that need to interface with yours. I'm in the exact same situation myself ATM, with 4 companies writing different parts of a complex system. The other people/companies need to be able to coordinate their efforts with yours. I would be mightily p!ssed off if I had to trawl through source code looking for what each one was expecting as interfaces (not meaning this in a language feature way here). Cheers, Jim Cooper Jim, I hear what you're saying, but doesn't the requirements document cover that? All I'm having problems with is the need for both a requirements and a design document. Given that the requirements are already specified, in what way does a design document provide any additional information that a prototype can't? Scout Back to top Jim Cooper Guest Posted: Tue May 09, 2006 12:14 pm    Post subject: Re: Design documents versus prototypes Quote: I'm trying to figure out exactly what a "bollocking" is. Bollocks = testicles If something is the dog's bollocks, it's a good thing. Getting a bollocking (or worse, getting a right bollocking) is being told off in a vigourous manner. Quote: Is it kinda like a methaphorical butt-kicking? Yes, except that it should be kick up the arse, if you want to stay in the same vernacular, and it may or may not be metaphorical :-) Cheers, Jim Cooper _____________________________________________ Jim Cooper jcooper (AT) tabdee (DOT) ltd.uk Skype : jim.cooper Tabdee Ltd http://www.tabdee.ltd.uk TurboSync - Connecting Delphi to your Palm _____________________________________________ Back to top Eric Grange Guest Posted: Tue May 09, 2006 1:14 pm    Post subject: Re: Design documents versus prototypes Quote: When it comes to delivery and budget, which is better? do it their way (with docs galore), delivery unknown and blow the budget, or my way with guaranteed delivery (taking into account 3rd parties) and within budget? There is no absolute answer IMO, if a low-on-documents relationship can work quite well and to the benefits of both parties, it also requires some form of trust and relationship to already be in place before it can work: an understanding that you will do the right thing, and that they won't be nitpicking. Quote: I guess the biggest difference between the many systems is that while there is one of me (with a Delphi compiler), there are at least 8 folks doing the COBOL stuff, and 7 BAs saying what should be done. This has a downside however: your lobbying pressure is much reduced. If something should ever go wrong and they want your share of the cake, it'll be 8+ of them lobbying to say they should have gotten the work instead of you - or maybe that they should have hired X more of them to do it... ;) Eric Back to top Eduardo A. Salgado Guest Posted: Tue May 09, 2006 1:14 pm    Post subject: Re: Design documents versus prototypes Scout, PMFJI. Learn to do it their way. If "> No-one is ever going to hire me now. I'm too old, too opinionated and ..." Then protect yourself. If this company has been "telling you for 14 years" they could some day find someone using Delphi who is also willing to give them better documentation and you are out of a job that you obviously do very well. Learn new things. Learn to document and to still deliver on time. Do not think of it as prototypes but as the things you tell yourself in your mind as you start to plan the project. Sort of "... hmm, I think this is going to take me some 3 months. ... This thing has to tie into the existing system just that way or things break... I think I'll do it using these components,...", etc. What is a day or so in putting your thoughts to paper if it improves your relationship with your customer? Use templates, just like you use old code. If it takes you more than a day (over a period of a week or so) to write most of the documentation, then your may be wasting too much time. HTH. - Eduardo It took me seventeen years to get 3,000 hits in baseball. I did it in one afternoon on the golf course. -- Hank Aaron Eminent Domain Software "Custom Software Development For Your Domain" Makers of EDSSpell, EDSPrint, EDSZipCodes and XSpell, the IDE Expert. Scout wrote: Quote: What's your experience? I have a love-hate relationship with this customer: love because I always deliver, hate because I don't always do it their way. When it comes to delivery and budget, which is better? do it their way (with docs galore), delivery unknown and blow the budget, or my way with guaranteed delivery (taking into account 3rd parties) and within budget? Back to top Jim Cooper Guest Posted: Tue May 09, 2006 1:14 pm    Post subject: Re: Design documents versus prototypes Quote: I hear what you're saying, but doesn't the requirements document cover that? I don't know, I can't see it Typically the ones I deal with do not specify that sort of thing in sufficient detail. Quote: Given that the requirements are already specified, in what way does a design document provide any additional information that a prototype can't? It provides information in a form other people can read, and usually at a higher level than code. I would expect class or component diagrams, and possibly sequence or activity diagrams (meaning UML diagrams here), for example, the first in each pair being the more low-level detail. Cheers, Jim Cooper _____________________________________________ Jim Cooper jcooper (AT) tabdee (DOT) ltd.uk Skype : jim.cooper Tabdee Ltd http://www.tabdee.ltd.uk TurboSync - Connecting Delphi to your Palm _____________________________________________ Back to top Jim Cooper Guest Posted: Tue May 09, 2006 1:14 pm    Post subject: Re: Design documents versus prototypes Also, I know it was probably an example, but I wouldn't like to see anything in an event handler on a form that indicated that was were the code was going to end up in the real version. Cheers, Jim Cooper _____________________________________________ Jim Cooper jcooper (AT) tabdee (DOT) ltd.uk Skype : jim.cooper Tabdee Ltd http://www.tabdee.ltd.uk TurboSync - Connecting Delphi to your Palm _____________________________________________ Back to top Joanna Carter [TeamB] Guest Posted: Tue May 09, 2006 3:14 pm    Post subject: Re: Design documents versus prototypes "Oliver Townshend" <oliveratzipdotcomdotau> a écrit dans le message de news: 44607a18 (AT) newsgroups (DOT) borland.com... |> I'm trying to figure out exactly what a "bollocking" is. | > Neither I nor "dictionary.com" know. Is it kinda like | > a methaphorical butt-kicking? | | Yes, except your b******s are on the opposite side of your body. Only for roughly half the popuation Please moderate the language a bit chaps, after all these groups are meant to be family friendly for all those budding school programmers as well as those of us who are slightly more refined . Joanna -- Joanna Carter [TeamB] Consultant Software Engineer Back to top Bob Guest Posted: Tue May 09, 2006 5:14 pm    Post subject: Re: Design documents versus prototypes Scout wrote: Quote: I'm frequently given tasks by a huge corporate customer with a heterogenous IT system and more Business Analysts and consultants that you could shake a stick at (even if you were particularly adept at stick-shaking). At a project review today which covered multiple projects, the customer acknowledged that I had delivered the required code in less time than the already very tight time-frame, and that the cost was under what they had budgeted for. Then I got a bollocking for not producing design documents so that the BAs and consultants could see what they were going to get. The only thing that I could think of saying in my defense was 'I did give you the design documents, but instead of being written in Word, they were written in Delphi, they worked, and showed you precisely what you were going to get'. I had taken the requirements document and used the RAD power of Delphi to show exactly how the system would work in less time than it would have taken me to come up with a bunch of words that conveyed much less information. Since the data access layer didn't exist when I created the prototype, I used things like: procedure TMyForm.OnBarcode(sender : TObject; const Barcode : string) begin {$IFDEF FAKE} // code that responds with some hard-coded values // and shows what should happen {$ELSE} // no code here, but this is where I'll write the real stuff {$ENDIF} end; ...and put some real logic into the FAKE part so that all eventualities could be tested as long as they stuck to the hard-coded barcodes. I know that I'll never win the battle of words versus work. The Project Manager even said "This is the same problem we've had with you for the last 14 years, but you always deliver on time (or before time) and on or under budget", so she's not going to win either. What amazes me is that few corporates ever take advantage of the incredible power that Delphi provides in being able to produce working prototypes in a very short time. I also got a bollocking for refusing to commit to a delivery date. As I said, this is an heterogenous system, and when I built the prototype, the data access layer didn't exist and was provided by another party. I was happy to commit to "3 days after the data is available, you can have your Delphi system", but project managers often don't see that as a commitment. Some of the parts of the system were written in Java, others in COBOL, and the rest is Delphi. The Java part slipped under the radar 'coz none of the BAs actually understand what it does, and it seems that for COBOL stuff you really need to write documents specifying what is going on (or is planned) while the Delphi stuff just works. Don't get me wrong: if there is a need to write database design documents to illustrate how the data relationships are going to work, then I'm your man. But if the proof in the pudding is whether or not the solution is going to fulfill the requirements, then I reckon that a prototype wins hands down every time. And it seems that amongst all of the tools available to all of the people that work with these projects, only Delphi is able to produce working prototypes within the sort of timeframes that we are given. The other thing that I love about Delphi is that there's not too much trouble in turning a prototype into a working system. Yeah, we can mess about with the prototype till the cows come home, but when the customer finally agrees that the prototype does what is required, there's very little work left to do. What's your experience? Scout Well. I tend to think like you. I just want to get the thing done, on time and working as flawlessly as possible. I look at it this way. Prototypes are for the end (user) customer. It allows them to see work flows and functionality that they want. They don't need design documents nor do they usually understand them. With that said, unless you are a one man shop, there are usually others that will have to maintain your code and write additions and access your data. For these folks you really need some documentation. Unless the program is extremely simple, it is not easy to just look at a prototype and understand the inner workings of the software. Even for programs that I write entirely myself, if I come back to them in several years, I often find myself scratching my head wondering "what was I thinking here". Liberal use of comments help, but design documentation is usually the best solution. As someone else pointed out earlier. The prototype is a miniture of a building. Shows where rooms, doors, windows, etc are located. However, it doesnt necessarily show the plumbing system, electrical system, air ducts, etc. -- Back to top Wayne Niddery [TeamB] Guest Posted: Tue May 09, 2006 5:14 pm    Post subject: Re: Design documents versus prototypes Scout wrote: Quote: The only thing that I could think of saying in my defense was 'I did give you the design documents, but instead of being written in Word, they were written in Delphi, they worked, and showed you precisely what you were going to get'. procedure TMyForm.OnBarcode(sender : TObject; const Barcode : string) begin {$IFDEF FAKE} // code that responds with some hard-coded values // and shows what should happen {$ELSE} // no code here, but this is where I'll write the real stuff {$ENDIF} end; Sorry Scout, but this is not documentation, it tells them nothing except that there's no real code yet, but then if there was, they shouldn't have to read it to figure out what the program is doing. Yes, Delphi is great for slapping together a "working" prototype in order to show design/UI ideas to a customer, but the key words here are "slapping together"; I create these with less than well thought out architecture and they are generally held together with virtual paperclips and bubblegum - precisely because I have no intent to turn the prototype into the actual product and don't think it is a good idea to do so. Quote: Don't get me wrong: if there is a need to write database design documents to illustrate how the data relationships are going to work, then I'm your man. But if the proof in the pudding is whether or not the solution is going to fulfill the requirements, then I reckon that a prototype wins hands down every time. A prototype does not explain how it fulfills requirements, one must make an effort to read requirements and then figure out in your prototype where it is addressed and how it works - and then may not really get it because it isn't complete or real. If a requirements document is anywhere near complete, then you should be able to create functional and programming specification documents that address the requirements - and in here you can certainly include screen shots to help explain how requirements are being addressed, but words *are* needed because it is much easier for others to make sense of that then an incomplete, *fake*, model they have to explore. Furthermore, these documents can be used as a source to easily create a user manual for the completed program. As far as delivering on time and on budget, you can still do that as long as you include the time to produce these documents in your estimates - they are a legitimate part of the job, you don't have to produce them for free or allow them to threaten your schedule. -- Wayne Niddery - Logic Fundamentals, Inc. (www.logicfundamentals.com) RADBooks: http://www.logicfundamentals.com/RADBooks.html "Bandwagons are like streetcars, there'll be another along in a few minutes." Back to top Display posts from previous: All Posts1 Day7 Days2 Weeks1 Month3 Months6 Months1 Year Oldest FirstNewest First         BorlandTalk.com Forum Index -> Delphi Non-Technical All times are GMT Goto page 1, 2  Next Page 1 of 2   Jump to: Select a forum C++ Builder Newsgroups----------------C++ BuilderC++ Builder (ActiveX)C++ Builder (Announcements)C++ Builder (Command Line Tools)C++ Builder DatabasesC++ Builder Databases (ADO)C++ Builder Databases (Desktop)C++ Builder Databases (InterBase Express)C++ Builder Databases (Multi-Tier)C++ Builder Databases (SQL Servers)C++ Builder (Graphics)C++ Builder (IDE)C++ Builder (Internet)C++ Builder (Internet Socket)C++ Builder (Internet Web)C++ Builder (Jobs)C++ Builder (Language)C++ Builder (Language C++)C++ Builder (Compatibility with MFC)C++ Builder (Native API)C++ Builder (Non-Technical)C++ Builder (Students)C++ Builder (Third Party Tools)C++ Builder (Upgrade)C++ Builder (VCL)C++ Builder (VCL Components Usage)C++ Builder (VCL Components Development)C++ Builder (VCL Usage)C++ Builder (WinAPI)C++ Builder Installation Delphi Newsgroups----------------Delphi (General)Delphi ActiveX Controls UsageDelphi ActiveX Controls DevelopmentDelphi As400Delphi DatabasesDelphi Databases (ADO)Delphi Databases (dbExpress)Delphi Databases (Desktop)Delphi Databases (InterBase Express)Delphi Databases (Multi-Tier)Delphi Databases (SQL Servers)Delphi DeploymentDelphi GraphicsDelphi IDEDelphi InternationalizationDelphi InternetDelphi Internet Isapi-WebBrokerDelphi Internet WebSnapDelphi Internet WinsockDelphi JobsDelphi Language BASMDelphi Language ObjectPascalDelphi Model Driven Architecture (General)Delphi Model Driven Architecture (Third Party)Delphi MultimediaDelphi Native APIDelphi Non-TechnicalDelphi ObjectPascalDelphi OLE AutomationDelphi OO designDelphi OpenToolsAPIDelphi Reporting-ChartingDelphi RTLDelphi StudentsDelphi TeamSourceDelphi Thirdparty ToolsDelphi Thirdparty Tools (General)Delphi Thirdparty Tools (IntraWeb)Delphi Thirdparty Tools (RaveReports)Delphi UpgradeDelphi VCLDelphi VCL ComponentsDelphi VCL Components UsingDelphi VCL Components WritingDelphi WebServices SOAPDelphi WinAPIDelphi XMLDelphi Installationcomp.lang.pascal.delphi.components.misccomp.lang.pascal.delphi.components.usagecomp.lang.pascal.delphi.components.writingcomp.lang.pascal.delphi.databasescomp.lang.pascal.delphi.misccomp.sources.delphi JBuilder Newsgroups----------------JBuilderJBuilder AnnouncementsJBuilder Applet IssuesJBuilder As400JBuilder CompilerJBuilder CORBA/RMIJBuilder DatabasesJBuilder DB SwingJBuilder DebuggerJBuilder DeploymentJBuilder DocumentationJBuilder EnterpriseJBuilder HandheldJBuilder IDEJBuilder JavaJBuilder JavaAPIJBuilder Java LanguageJBuilder Java SwingJBuilder Java BeansJBuilder Java Beans UsageJBuilder Java Beans DevelopmentJBuilder JBCLJBuilder JDataStoreJBuilder JobsJBuilder LinuxJBuilder MacintoshJBuilder & MobileSetJBuilder MultiLingual AppsJBuilder Non-TechnicalJBuilder OpenToolsJBuilder Servlets (JSP)JBuilder StudentsJBuilder Team DevelopmentJBuilder Thirdparty ToolsJBuilder UpgradeJBuilder Installation InterBase Newsgroups----------------InterBaseInterBase Bug DiscussionInterBase GeneralInterBase IBConsoleInterBase OpenSourceInterBase ReplicationInterBase SQLInterBase ThirdpartyInterBase Installation Miscellaneous Borland Newsgroups----------------AppCenterAppServerEnteraVisiBroker  You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum Powered by phpBB © 2001, 2006 phpBB Group SEO toolkit © 2004-2006 webmedic.