Re: What sort of documentation is most useful for a java application?
- From: Arne Vajhøj <arne@xxxxxxxxxx>
- Date: Fri, 30 Mar 2007 21:08:29 -0400
frustratedprogrammer@xxxxxxxxx wrote:
I'm interested in other's experiences as to what types of
documentation for java are most useful. Obviously Java docs are very
common and very widely used. Apart from java docs however what do
people find useful?
I know a lot of managers feel that a system should have a certain
amount of documentation supporting it, but in my experience often
documentation that is produced for this purpose never gets used after
it is written. I would suspect some sort of high level design of the
system which describes it's interfaces, major architectural components
and design patterns is useful. Perhaps also a support/operations
manual for those that need to support the system in production can be
useful. However when it gets down to detailed design documents such
as class diagrams and sequence diagrams I rarely find them useful.
Usually they don't get maintained and they just don't help you
understand the system that much.
Although I'm not totally convinced I'm starting to lean towards the
idea that good software is self documenting and software quality is
more important than documentation. Also having been involved in some
agile projects lately, I'm starting to see how the automated tests for
a system can be the best documentation of what the system does.
The most common error with class diagram and sequence diagrams is
to try and make them complete. They are much more useful if they
only show the most important information.
Keeping documentation up to date is just another rule that needs
to be enforced like unit tests, code style etc.etc..
Arne
.
- References:
- What sort of documentation is most useful for a java application?
- From: frustratedprogrammer
- What sort of documentation is most useful for a java application?
- Prev by Date: Re: problems with Java
- Next by Date: Re: Best database for implementing a cache
- Previous by thread: What sort of documentation is most useful for a java application?
- Next by thread: Re: Month difference between dates
- Index(es):
Relevant Pages
|
