(e-mail address removed) skrev:
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?
To mirror what someone else said, there are levels of documentations;
the best documentation is the documentation that gives you the level
of detail that you require. A tester might want to know the overall
flow of a feature and the ultimate change that triggering this feature
has on the overall system; he probably doesn't care about method
signatures. On the other hand, the designer that's to maintain the
feature needs to know precisely these method signatures. A user of the
feature only needs to know the interface that the feature exposes,
etc. Many documents that one person sees as good, another will see as
bad.
Architecture has long known about these different, "Views," for
different, "Stakeholders," for example: logical view, deployment view,
process view, etc. I'm unaware of as rigorous a distinction on source-
code level.
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.
Again, there is no, "Useful," documentation without considering for
whom the documentation is written. I doubt a manager would see much
use in class and sequence diagrams.
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.
Do you rarely find them useful because they are inherently bad or
because they don't answer the questions you're asking? If the latter,
it could be because you are asking inappropraite questions of the
documentation. You don't get a good overall view of a system from
class-diagrams (if the system is of any reasonable size); you don't a
good idea of how a system is deployed over various computing devices
by looking at the JavaDoc, etc.
Class diagrams fail to provide a good overall view of a system because
they are not, "Comprehension-scalable," in other words, their
complexity is usually proportional to their number.
Package diagrams offer a much better granule for overall comprehension
(but fail to provide much information on dynamic behaviour).
Hierarchical package diagrams are better still.
Usually they don't get maintained and they just don't help you
understand the system that much.
Documentation is only as good as the process that maintains it, that's
true.
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.
"Self-documenting software;" I'm not sure what you mean by that, but
I'll presume here you mean that you can gain an understanding of the
code by reading the code itself. If so, and if this is your only
source of documentation, then you've already alienated everyone who
isn't used to looking at source code, which usually means the managers
that have to budget for the software's maintenance (yes, some managers
do read source code, but not all).
Note also that encapsulation has implications for source-code-level
documentation, too. An object should know precisely what it does, and
very little else; particularly, it should know very little about the
objects that use its services. The documentation for an object, thus,
usually won't describe the objects that use it; in other words, its
documentation is as encapsulated away from the rest of the system as
its behaviour.
"Software quality is more important than documentation." An
interesting observation.
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.
Depends on the user of the documentation because ... well, you get my
point.
For what it's worth, I think there will always be a place for
documentation describing an application in an introductory manner (as
there will always be new people who want to know, "What the
application does," if that application is successful). I find it
useful when this introductory documentation also points to the source
code where needed, but without filling the documentation itself.
Traditional, static documentation (Word and Framemaker documents, for
example) seem more clumsy at handling such references than HTML.
Here's an example of a small application's documentation; the
documentation is targetted at two types of programmer: the programmer
who wants an overall view of how the application works, and the
programmer who must maintain the application. Admittedly, these are
quite close roles, certainly closer than a programmer to a manager,
but I think it would be relatively easy to add a third, manager level
of documentation that would refer to the text here (which in turn
refers to the source code).
The beauty of this example is: you can make up your own mind, and
whatever decision you arrive at is unarguably correct. For you.
If you read it (or just enough to get a flavour; it's not trivially
short) and at the end have no idea what this application does or how
it does it, then the documentation has failed. If, furthermore, you
want to know not only the overall application, but also a very
specific implementation of some contained solution, then, too, the
documentation has failed:
http://www.edmundkirwan.com/servlet/fractal/cs1/frac-cs10.html
..ed
