Login | Register
My pages Projects Community openCollabNet

argouml
Wiki: Diff for "Organization of ArgoUML documentation"

Edit this page | Links to this page | Page information | Attachments | Refresh page

 

Differences between revisions 2 and 4 (spanning 3 versions)

Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
 1. The web sites  1. The users' web site
Line 7: Line 7:
 1. The cookbook  1. The developers' web sites and wiki
Line 12: Line 12:
These different bits have all different purpose and audience and the purpose of this chapter is to try to define that. These different bits have all different purpose and audience and the purpose of this page is to try to define that.
Line 16: Line 16:
=== Web site(s) === === Users' Web site(s) ===
Line 21: Line 21:
 * the central point of the ArgoUML development project.
Line 25: Line 24:
 * developers in the project,
Line 30: Line 28:
 * References to all the other parts of the documentation. Current project information like the contents of the upcoming releases and the plan for the nearest future. Easy access illustration for new users. Some illustrations that do not fit in other parts. This is done as a complement to the other parts. Examples, tours.  * 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.
Line 61: Line 59:
=== Cookbook === === The developers' web sites and wiki ===
 * The central point of the ArgoUML development project.
Line 67: Line 66:
This is for developers writing code, maintaining the documentation or the web site. This is for
 * developers in the project,
 * people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools.
Line 75: Line 76:
 . The Cookbook contains one section for each subsystem where the internal design of that subsystem is kept.  . The wiki contains a page for each subsystem where the internal design of that subsystem is kept.
Line 98: Line 99:
The Cookbook, 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.
CategoryFix: The Cookbook will no longer be DocBook.
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.

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.

  1. The users' web site
  2. The manual and quick-guide
  3. Help texts within the running ArgoUML
  4. The FAQ
  5. The developers' web sites and wiki
  6. The javadoc of API and SPI of a subsystem
  7. The code, variable names, class names
  8. 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.


CategoryFromCookbook

Organization of ArgoUML documentation (last edited 2009-04-18 07:01:07 -0800 by linus)