What tools and standards do you use to describe your project, database, modules, classes, their interaction for programmers, let's say after the project is finished.
Do you use UML?
Are there enterprise standards for Java developers, how to write such a documentation let's say from SUN?
Are there specific tools that simplify this documentation process & compilation of neccessary docs.
If there are good books on project documenting process,
please give me links to Amazon.
In my opinion, for algorithms and complicated processes that include a lot of mathemtics, LaTeX is nice. It can also be used for not-so-mathematical purposes, but is especially good for maths.
You can use any of the tools like Microsoft Visio ,ARIS Express, AmaterasUML eclipse plugin, or netbeans IDE feature for creating models.
Each organization has their own standards for documentation of project. In general the hierarchy includes the doc versioning, project scope, objectives, and module details of the projects (may or may not be accompanied by model/Prototypes).
You can try this book: Read me first
You need to have brilliant javadoc - which honestly helps much more than any kind of documentation :) As for UML - yes, from my experience Enterprise Architect is rather brilliant, after messing with some settings it may GENERATE pretty good documentation :) If you follow software engineering recommendations, it'll be prety good and widely accepted.
I'm afraid there is no standard. It really depends on who you work for. If you are lucky and don't have to deliver huge technical doc to clients, it's a good idea to keep documentation close to the code. And to keep the code clean and easy to read.
At our company, all we do is two things:
1.) Along with a short intro and install instructions, we explain the big picture in APT files inside the projects (only as much as necessary). From time to time we also add diagrams here, but only if it's really helpful. Our continious integration server automatically generates pretty html from these files. This way the doc is always updated and follows the code's progression.
2.) Comment tricky code pieces with javadoc. Our continious integration server again generates pretty html from javadoc.
Depending on how valuable it is for the project, you could also integrate a bunch of other maven plugins to automatically generate class diagrams, dependency diagrams and so on.
The feature I use for documentation is to:
I can only do it with EclipseUML Omondo because the other tools are not java oriented. Omondo first map your full java project to UML 2.2. The reverse is just amazing because you reverse the full project at multiple packages level. Whaoo !!
I mean relation between packages, java annotations, associations etc..I have checked with Enterprise Architect, Rational and Omondo reverse is a lot better. For example you can have interface in one package inherited from classes in another package. The reverse can detect it and add this information in the model. Really cool and useful because I always separate my interfaces and classes and will certainly not model them into the same package :-) Once the model has been created you can code and update your project and EclipseUML will be updated automatically.
The database mapping is covered by java annotations (e.g. @Entity) which are generated in the code from the diagram or which are synchronized from code to the diagram. No more problem for modeling my database into my class diagram and adding all comments I need.
I don't think that adding my documentation directly in the model as text at the root of the model element is a hack. This is cool and everybody in the team can see each other comments. This make life easier and is an additional more business oriented documentation to the javadoc which is more code oriented. The UML specification never said it is not allowed to add txt documentation directly in the model so why not to use it ? It could graphical or just txt but I prefer txt because graphical UML notation is sometimes too hard to understand. I therefore reverse the class diagram, add few notes (e.g; yellow colors) and everything else as txt comment in the model. No risk to make mistake and full documentation immediately available in the workspace of each developer. Each developer can also update the documentation if during the implementation stage something is changed. It means that the documentation is always accurate and everybody is involve and not just the modeler.
We do pretty much the same as @deadsven:
(We have a separate Hudson CI system, and use it to run various Sonar reports on static code "quality" and test case coverage. But that is not integrated with our documentation trees.)
We focus our documentation effort on aspects that people are likely to read, and that they cannot get by using the software visualization capabilities of a decent IDE. We also try to avoid writing documentation that is likely to get out of date ... and therefore become useless ... as the project evolves.
One of the nice things about Maven-based documentation is that you can develop the hand-written stuff incrementally and check it into the source-code repository together with the source code. You can generate an up-to-date documentation tree as HTML any time you feel like, and if you want look at the documentation from 3 months ago that is trivial as well. (I personally don't find UML diagrams, etc all that helpful, but it is interesting to note that there are Maven plugins to generate them.)
for programmers? let them read code.
when code isnt' very descriptive, write some documents in plain English. Draw whatever pretty pictures that may help understanding.
No UML.
Javadoc is essential, but not enough. It is usually too fine-grained for someone trying to understand the architecture and design of a library or framework. UML is nice for illustration, but in most cases you still need some plain text documents like an Architecture Overview or a User Manual.
I like Docbook XML for writing such documents. You can check it in with your sources, your repository does not get bloated with large binaries like office documents, and you can integrate the HTML or PDF generation into your build process with the docbkx-maven-plugin.
Docbook is used by many large open source projects like JBoss or Spring Framework.
For WYSIWYG editing, you can use the XMLmind editor.