>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
