There are eight (8) significantly different bits of documentation in the ArgoUML project. By documentation I mean some information of the product that is developed alongside the product and that has a persistent value.
- The users' web site
- The manual and quick-guide
- Help texts within the running ArgoUML
- The FAQ
- The developers' web sites and wiki
- The javadoc of API and SPI of a subsystem
- The code, variable names, class names
- The javadoc
These different bits have all different purpose and audience and the purpose of this page is to try to define that.
Bits of documentation
Users' Web site(s)
Is
- an entry point for the other parts of the documentation.
- the main download area for the ArgoUML product.
- the central point of the ArgoUML user community.
This is for everyone, i.e.
- users of the product, and
- people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools.
Contains:
- References to all the other parts of the documentation. Current project information like the contents of the upcoming releases. Easy access illustration for new users. Some illustrations that do not fit in other parts.
Manual and quick-guide
Describe how ArgoUML is installed and used. Describe how UML is used with ArgoUML.
This is for
- Users of ArgoUML.
- Persons that want to evaluate ArgoUML for the purpose of starting to use it.
- Persons that are training to use UML and ArgoUML.
Contains:
- Complete installation instructions for all supported installation schemes.
- Complete description on how to use ArgoUML in your project.
- Complete reference on how to use ArgoUML.
Help text in ArgoUML
Give a quick help with a specific feature or button. Give short explanations of all commands and actions.
This is for the Users of ArgoUML.
Contains: * A complete set of quick help and explanations.
FAQ
Cope for shortcomings in ArgoUML, the help text, the Manual and quick-guide and the web site.
This is for the Users of ArgoUML and the Members of the users mailing list.
Contains:
- A list of issues that are not addressed in the other part of the documentation. It is written in questions-answers-format and the contents is governed by the issues discussed recently in the user community.
The developers' web sites and wiki
- The central point of the ArgoUML development project.
- Make it possible to learn how ArgoUML works and how to extend it.
- Lower the threshold for new developers.
- Reduce the amount of knowledge of complex design and reasons for certain design decisions, that are documented only in the heads of the developers.
- Reduce the amount of simple questions on the developers' mailing list.
This is for
- developers in the project,
- people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools.
Contains:
- Instructions on how to add new functions and behavior.
- Instructions on how to build and publish a release. The purpose of this is to control the generation of each release.
- Project policies like what level of quality is aimed for and description of processes that achieves that level.
- The documentation of the development environment and how to set it up.
- The design, where it is so complex or involves so many classes and methods that it is meaningless to store it in the javadoc of the involved classes and methods.
- The wiki contains a page for each subsystem where the internal design of that subsystem is kept.
- Design decisions as a collection of knowledge around how and why the project makes certain decisions.
Javadoc of API and SPI of a subsystem
Explain how to use the subsystem.
This is for developers that work with other parts of ArgoUML that interacts with the subsystem in question.
Contains:
- Description of the function of all public classes, all public and protected methods, variables, and constants.
Javadoc of non API- and SPI-parts
Document the code to understand it later.
This is for developers writing code in the same subsystem.
Contains:
- Together with other comments and variable names, this is the description of the functions of all classes, operations, methods, variables, and constants.
Source Code
Implement ArgoUML in a maintainable and understandable way. See Standards for coding in ArgoUML for details on how to write the code.
The User Manual, and the Quick Guide, are all written in docbook and generated into HTML and PDF during deployment. See Writing Documentation in the ArgoUML Project for details on how to write these.