we still struggle with the best balance. However, I use a
couple of simple guidelines that have worked very well
for me in almost all cases (there have been some times
when I've lived to regret some decisions).
Use case work flows are the bread and butter of the
documentation and all others flow from them. Each of the
high-level processes needs to be broken down into lower
level processes and so forth. Without these documents
there is no point in writing the application. They also
provide a model for moving through processes in the
application and the order those process should occur.
They also point out areas of re-usability. From this
comes the object model.
I believe that you must have a UML object model. No
arguments. The objects must relate back to the user
requirements for traceability. So if the user says the
app needs to do this you better be able to say which
classes support that process. This helps eliminate any
extraneous classes. This does not mean that you need a
model down to the method level. If you aren't using any
code generation techniques (which I have found to get a
project only part of the way) it isn't important and
requires too much upkeep. The problem with most
documentation is that if it is too large no one will
either read it or update it and it becomes worse than no
documentation at all in my experience.
Sequence diagrams are things that I require for specific
tasks and design patterns. For example, in my book I have
a specific pattern for editing lookup tables which
involves loading a proxy, loading a record, editing a
record, checking business rules, saving a record,
handling concurrency issues. I have a set of sequence
diagrams that outlines this particular pattern. I also
have sequence diagrams for subsets such as just the
concurrency section of the process which can be used for
other processes.
The only other piece of documentation that I routinely
require is a deployment diagram. If you don't know how
the objects are going to communicate across app domains
then all bets are off when it comes to designing the
basic infrastructure and that's just a disaster waiting
to happen.
Other pieces of documenation are required depending on
the project, but these are the big four. I won't start a
project without them anymore.
Hope that helps.
Jeff Levinson
Author of "Building Client/Server Applications with
VB.NET: An Example Driven Approach"
-----Original Message-----
I don't know if this is the best place to put this, but...
I was having a discussion with developer/architect friends of mine on thesubject of what documentation was important to have before coding began on aproject. We had arguments that depending on the size of the project,certain documentation and design had to be done, for example, class diagramsand object diagrams.
Another argument stated that sequence diagrams or some type of flowchart anda class diagram would be enough to handle all documentation that was neededfor technical and non-technical people involved with the project.
Personally, I argue that the more documentation (usable) the better, butwhere do we draw the line when it comes to architecture and design docs?Any opinions?
tia
.
