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 1 and 4 (spanning 4 versions)

Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
   1.  1. The users' web site
 1. The manual and quick-guide
 1. Help texts within the running ArgoUML
 1. The FAQ
 1. The developers' web sites and wiki
 1. The javadoc of API and SPI of a subsystem
 1. The code, variable names, class names
 1. The javadoc
Line 5: Line 12:
      The web sites
   2.
These different bits have all different purpose and audience and the purpose of this page is to try to define that.
Line 8: Line 14:
      The manual and quick-guide
   3.
== Bits of documentation ==
Line 11: Line 16:
      Help texts within the running ArgoUML
   4.

      The FAQ
   5.

      The cookbook
   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 chapter is to try to define that.

Table C.1. Bits of documentation
Bit Main purpose Contains
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.
    *

      the central point of the ArgoUML development project.
=== 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.
Line 49: Line 24:
    *  * users of the product, and
 * people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools.
Line 51: Line 27:
      developers in the project,
    *
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.
Line 54: Line 30:
      users of the product, and
    *

      people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools.

 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.
Manual and quick-guide
=== Manual and quick-guide ===
Line 65: Line 34:
 * 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.
Line 66: Line 38:
    * 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.
Line 68: Line 43:
      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.



    *

      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
=== Help text in ArgoUML ===
Line 93: Line 47:
 A complete set of quick help and explanations.
FAQ
Line 96: Line 48:
Contains:
* A complete set of quick help and explanations.

=== FAQ ===
Line 99: Line 55:
 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.
Cookbook
Line 102: Line 56:
    * 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.
Line 104: Line 59:
      Make it possible to learn how ArgoUML works and how to extend it.
    *
=== 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.
Line 107: Line 66:
      Lower the threshold for new developers.
    *
This is for
 * developers in the project,
 * people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools.
Line 110: Line 70:
      Reduce the amount of knowledge of complex design and reasons for certain design decisions, that are documented only in the heads of the developers.
    *
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.
Line 113: Line 79:
      Reduce the amount of simple questions on the developers' mailing list.

This is for developers writing code, maintaining the documentation or the web site.

    *

      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 Cookbook contains one section 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
=== Javadoc of API and SPI of a subsystem ===
Line 143: Line 83:
 Description of the function of all public classes, all public and protected methods, variables, and constants.
Javadoc of non API- and SPI-parts
Line 146: Line 84:
Contains:
 * Description of the function of all public classes, all public and protected methods, variables, and constants.

=== Javadoc of non API- and SPI-parts ===
Line 148: Line 90:
Developers writing code in the same subsystem.
 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 Chapter 7, Standards for coding in ArgoUML for details on how to write the code.
This is for developers writing code in the same subsystem.
Line 152: Line 92:
The Cookbook, the User Manual, and the Quick Guide, are all written in docbook and generated into HTML and PDF during deployment. See Chapter 8, Writing Documentation in the ArgoUML Project for details on how to write these. Contains:
 *
Together with other comments and variable names, this is the description of the functions of all classes, operations, methods, variables, and constants.

=== Sourc
e Code ===
Implement ArgoUML in a maintaina
ble and understandable way.
See ["Standards for coding in ArgoUML"] for details on how to write the code.

T
he 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)