Coding and Implementation Documentation

Chapter 6 - Documenting the Project
byAndrew Filevet al.?
Wrox Press ©2002

	Team FLY

It seems that we've talked a bunch about writing software, but we haven't written any software yet. Does that seem odd? Well, not if you've spent much time on large, new software projects that properly focused on gathering requirements and other early stage activities before anyone opened Visual Studio to start coding. As important as coding is, the several stages of a project that lead to coding are every bit as important. As we've seen up to this point, doing a good job in requirements development, architecture and detailed design increases your chance of delivering a successful product. From a cost standpoint, studies have shown (and common sense tells us) that fixing problems before coding starts is significantly cheaper than fixing problems after code is written. The later in a project a defect is discovered the more expensive it is to change, test, and make up lost time.

That having been said, what documentation role does UML and Visio play at this stage of the game? Well, several, and all of them are important.

Requirements Documentation for Coding

Some of the best sources of information on how an application should behave and why are found in the data we gather during requirements development. Coders should always have access to use cases and other documentation. Not only will it give a developer perspective from the user that they may not be able to get otherwise, but it will give the developer a chance to see some of the raw input the designers and architects of the application used in making their decisions. I'm a big believer in exposing the people who are responsible for making designs work have access to as much background information as possible to help them do their job. Of course, you don't want every junior developer on the team reading use cases every day, but if you give talented people access to information that helps them do their job it can only result in a better product in the end.

Architecture Documents for Coding

High-level design documents help developers understand where their particular "piece of the pie" fits into the "big picture". Seeing conceptual class diagrams of activity diagrams illustrating work flow of a large system pinned up on cubicle wall is a good sign that developers are working on understanding more than just their potentially small slice of the world. Similar to the points made regarding requirements documentation during coding stages, the more information you can give to the folks responsible for turning designs into reality, the better the product will be and the smoother the entire project will run.

In addition, it is altogether possible that developers working out issues at some detail level will uncover unseen flaws in product designs.

	Team FLY