RE: Technical documentation sample
Mike, Is the client confusing a technical document with a specification document? Andrew Scott Senior Coldfusion Developer Aegeon Pty. Ltd. www.aegeon.com.au Phone: +613 8676 4223 Mobile: 0404 998 273 -Original Message- From: Mike Kear [mailto:[EMAIL PROTECTED] Sent: Tuesday, 29 May 2007 4:35 PM To: CF-Talk Subject: Technical documentation sample I'm asked to provide some technical documentation for a project, and I've done what I think is necessary, but the client's saying no I need PROPER technical documentation. Not what you have done. Well I thought i'd done a pretty good job of documenting the project, but i guess not. Does anyone have a technical document I can look at, so I can see what he might be meaning? -- Cheers Mike Kear Windsor, NSW, Australia Adobe Certified Advanced ColdFusion Developer AFP Webworks http://afpwebworks.com ColdFusion, PHP, ASP, ASP.NET hosting from AUD$15/month ~| Upgrade to Adobe ColdFusion MX7 Experience Flex 2 MX7 integration create powerful cross-platform RIAs http://www.adobe.com/products/coldfusion/flex2/?sdid=RVJQ Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279419 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.4
Re: Technical documentation sample
Quite likely. Or since i've got no formal (i.e. university) training in IT, maybe I dont know what's expected. The project works. The client's happy with that. But it's the technical documentation he reckons is blow par.Could be too for all I know. The documentation that contains the data dictionaries, flow charts, that kind of stuff. If i could see a sample of such a document i could compare that with what i've done to see what I ought to do differently. Sadly, with this, google hasnt been my friend so far. Cheers Mike Kear Windsor, NSW, Australia Adobe Certified Advanced ColdFusion Developer AFP Webworks http://afpwebworks.com ColdFusion, PHP, ASP, ASP.NET hosting from AUD$15/month On 5/29/07, Andrew Scott [EMAIL PROTECTED] wrote: Mike, Is the client confusing a technical document with a specification document? Andrew Scott Senior Coldfusion Developer Aegeon Pty. Ltd. www.aegeon.com.au Phone:+613 8676 4223 Mobile: 0404 998 273 ~| Upgrade to Adobe ColdFusion MX7 The most significant release in over 10 years. Upgrade see new features. http://www.adobe.com/products/coldfusion?sdid=RVJR Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279420 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.4
Re: Technical documentation sample
He probably wants *how* it works, how to set it up etc what is required software wise (and how to set them all up) not necessary to document specific code blocks but at least what you need to do/have in order to get it to work should you wish to maintain/move/further a project without in depth training etc. This e-mail is from Reed Exhibitions (Gateway House, 28 The Quadrant, Richmond, Surrey, TW9 1DN, United Kingdom), a division of Reed Business, Registered in England, Number 678540. It contains information which is confidential and may also be privileged. It is for the exclusive use of the intended recipient(s). If you are not the intended recipient(s) please note that any form of distribution, copying or use of this communication or the information in it is strictly prohibited and may be unlawful. If you have received this communication in error please return it to the sender or call our switchboard on +44 (0) 20 89107910. The opinions expressed within this communication are not necessarily those expressed by Reed Exhibitions. Visit our website at http://www.reedexpo.com -Original Message- From: Mike Kear To: CF-Talk Sent: Tue May 29 07:49:16 2007 Subject: Re: Technical documentation sample Quite likely. Or since i've got no formal (i.e. university) training in IT, maybe I dont know what's expected. The project works. The client's happy with that. But it's the technical documentation he reckons is blow par.Could be too for all I know. The documentation that contains the data dictionaries, flow charts, that kind of stuff. If i could see a sample of such a document i could compare that with what i've done to see what I ought to do differently. Sadly, with this, google hasnt been my friend so far. Cheers Mike Kear Windsor, NSW, Australia Adobe Certified Advanced ColdFusion Developer AFP Webworks http://afpwebworks.com ColdFusion, PHP, ASP, ASP.NET hosting from AUD$15/month On 5/29/07, Andrew Scott [EMAIL PROTECTED] wrote: Mike, Is the client confusing a technical document with a specification document? Andrew Scott Senior Coldfusion Developer Aegeon Pty. Ltd. www.aegeon.com.au Phone:+613 8676 4223 Mobile: 0404 998 273 ~| Upgrade to Adobe ColdFusion MX7 Experience Flex 2 MX7 integration create powerful cross-platform RIAs http://www.adobe.com/products/coldfusion/flex2/?sdid=RVJQ Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279421 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.4
RE: Technical documentation sample
Hmmm... What is the purpose of him having this information, this is different dependant on the type of job and the methodology that is used to do the work in the first place. In an Agile approach there really is no such think, just stories that describe each task. It sounds like he is IT savvy, but sounds like he is out of touch. Andrew Scott Senior Coldfusion Developer Aegeon Pty. Ltd. www.aegeon.com.au Phone: +613 8676 4223 Mobile: 0404 998 273 ~| Upgrade to Adobe ColdFusion MX7 The most significant release in over 10 years. Upgrade see new features. http://www.adobe.com/products/coldfusion?sdid=RVJR Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279423 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=89.70.4
Re: Technical documentation sample
On Tuesday 29 May 2007, Mike Kear wrote: I've done what I think is necessary, but the client's saying no I need PROPER technical documentation. Not what you have done. I assume you've asked the client to explain where he feels it is lacking ? -- Tom Chiverton Helping to assertively envisioneer enterprise metrics on: http://thefalken.livejournal.com This email is sent for and on behalf of Halliwells LLP. Halliwells LLP is a limited liability partnership registered in England and Wales under registered number OC307980 whose registered office address is at St James's Court Brown Street Manchester M2 2JF. A list of members is available for inspection at the registered office. Any reference to a partner in relation to Halliwells LLP means a member of Halliwells LLP. Regulated by the Law Society. CONFIDENTIALITY This email is intended only for the use of the addressee named above and may be confidential or legally privileged. If you are not the addressee you must not read it and must not use any information contained in nor copy it nor inform any person other than Halliwells LLP or the addressee of its existence or contents. If you have received this email in error please delete it and notify Halliwells LLP IT Department on 0870 365 8008. For more information about Halliwells LLP visit www.halliwells.com. ~| ColdFusion MX7 by Adobe® Dyncamically transform webcontent into Adobe PDF with new ColdFusion MX7. Free Trial. http://www.adobe.com/products/coldfusion?sdid=RVJV Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279426 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=89.70.4
RE: Technical documentation sample
Is he looking for documentation that meets a certain CMMI level? I'd ask the client for an example of what they want, otherwise it is a moving target. -Original Message- From: Mike Kear [mailto:[EMAIL PROTECTED] Sent: Tuesday, May 29, 2007 1:35 AM To: CF-Talk Subject: Technical documentation sample I'm asked to provide some technical documentation for a project, and I've done what I think is necessary, but the client's saying no I need PROPER technical documentation. Not what you have done. Well I thought i'd done a pretty good job of documenting the project, but i guess not. Does anyone have a technical document I can look at, so I can see what he might be meaning? -- Cheers Mike Kear Windsor, NSW, Australia Adobe Certified Advanced ColdFusion Developer AFP Webworks http://afpwebworks.com ColdFusion, PHP, ASP, ASP.NET hosting from AUD$15/month ~| Macromedia ColdFusion MX7 Upgrade to MX7 experience time-saving features, more productivity. http://www.adobe.com/products/coldfusion?sdid=RVJW Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279438 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=89.70.4
RE: Technical documentation sample
Do you use CFC's? If so, you should load the component inspector and then convert the output to a PDF, combine them all and that should help to at least document your 'classes' and methods. In any case, it 'looks' impressive ;) Brook -Original Message- From: Andrew Scott [mailto:[EMAIL PROTECTED] Sent: May 28, 2007 11:55 PM To: CF-Talk Subject: RE: Technical documentation sample Hmmm... What is the purpose of him having this information, this is different dependant on the type of job and the methodology that is used to do the work in the first place. In an Agile approach there really is no such think, just stories that describe each task. It sounds like he is IT savvy, but sounds like he is out of touch. Andrew Scott Senior Coldfusion Developer Aegeon Pty. Ltd. www.aegeon.com.au Phone: +613 8676 4223 Mobile: 0404 998 273 ~| Upgrade to Adobe ColdFusion MX7 Experience Flex 2 MX7 integration create powerful cross-platform RIAs http://www.adobe.com/products/coldfusion/flex2/?sdid=RVJQ Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279501 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=89.70.4
Re: Technical documentation sample
I'm asked to provide some technical documentation for a project, and I've done what I think is necessary, but the client's saying no I need PROPER technical documentation. Not what you have done. Well I thought i'd done a pretty good job of documenting the project, but i guess not. Does anyone have a technical document I can look at, so I can see what he might be meaning? Did they give you any indication of what they expected? There are several documentation methodologies to follow and they can be radically different from one another even when documenting the same system. I've never worked anyplace that actually used the methodology that they claimed to use: instead they used a (sometimes small) slice of it and customized anything else they needed. I've used Summit-D (now manged by IBM but I used it long ago) and it was decent - we shaved it down but ended up with two primary documents: the functional spec and the technical spec. In theory the functional spec contained all of the functionality of a system/project. User interface information, style information, functionality inventory, etc. The technical spec contained all of the low-level information: database design, object models, APIs, etc. The functional was a high-level business document while the technical was a low-level developer document - together they pretty neatly described the system. Now we're using a heavily modified UML model: use cases, objectified system flows, etc. UML is designed (if used properly) to build documentation in layers: each layer informs adjacent layers and each covers specific topics or concerns. It's really quite good but pretty labor intensive compared to others. In addition we also have several specialized pieces of documentation that go to various other teams: +) The Build-Book describes all aspects of configuration/installation of the project. +) The Run Book describes all of the touch points (system dependecies) of the project, all contacts for the systems and all of the escalation procedures when things go wrong. +) The Data Inventory. For those projects that need it this would describe all of the data-related depencies of the system (tables, stored procedures, triggers, etc) and be managed by the various DBAs involved. +) A Style Guide. Essentailly a sub-set of the functional spec this is specifically (for those systems that need it) a visually-focused document describing fonts, spacing, colors, etc. It's mostly used by designers and is often based (at least in part) on corporate style standards. One of the best questions to get clear is what the audience for the documentation is. Is it technical (people that might work on the system)? Is it business (people that might own or manage development on the system)? Is is end-user (you'd be suprised how many people say project documentation when what they really mean is user manual)? A good set of documentation can easily take longer to produce than the system being documented. Having the documentation done (and, almost more importantly, making sure to manage and update it) can save you tremendous work and money later. I only wish more project factored documentation as prominently as it should be (it's usually the first thing to be slashed when time/money gets tight). In your case you really to need to determine what kind of documentation they're looking for. Otherwise you might work for weeks and still not touch upon the style or audience they're concerned about. Jim Davis ~| Create robust enterprise, web RIAs. Upgrade integrate Adobe Coldfusion MX7 with Flex 2 http://www.adobe.com/products/coldfusion/flex2/?sdid=RVJP Archive: http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:279516 Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=89.70.4
