Chapter 7. Organization of ArgoUML documentation

Linus Tolke

Abstract

This chapter contains written down ideas on what goes into what part of the documentation. These ideas are formulated by Linus Tolke.

Table of Contents

7.1. Overview
7.2. User Manual Plans
7.2.1. Target Audiences for the User Manual
7.2.2. Goals for the User Manual
7.2.3. Suggested Manual Structure
7.2.4. Actions, Priorities and Questions

7.1. Overview

There are seven 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 code, variable names, class names

  2. The javadoc

  3. The cookbook

  4. The web site in CVS

  5. The manual and quick-guide

  6. Help texts within the running ArgoUML

  7. The FAQ

These different bits have all different purpose and audience and the purpose of this chapter is to try to define that.

Table 7.1. Bits of documentation

BitAudienceMain purposeContains
The code
  1. Other developers that will maintain and improve on the code.

  2. The compiler.

Implement ArgoUML in a maintainable and understandable way. See Chapter 9, Standards for coding in ArgoUML for details on how to write the code.
The javadoc Developers writing code that communicates or in other ways interact with this class. Make it easy to see what the functions of every class are and how to use them. Description of the functions of all classes, all public and protected methods, variables, and constants.
The cookbook Developers writing code, maintaining the documentation or the web site. Make it easy to learn how ArgoUML works and how to extend it. Be a collection of knowledge around how everything is set up. Be a store of the agreed solution around fundamental design decisions i.e. design decisions that are so big that it is meaningless to store them in the javadoc. Be a collection of knowledge around how and why the project makes certain decisions. Instructions on how to add new functions and behavior. Instructions on how to do the chores around maintenance (build a release, publish a release, build the documentation part of the release, test ArgoUML, test the documentation, ...). Agreed project rules like what level of quality is aimed for and description of processes that achieves that level.
The web site in CVS Everyone, i.e. developers in the project, users of the product, people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools. Be an entry point for the other parts of the documentation. Be the main download area for the ArgoUML product. Be the central point of the ArgoUML user community. Be the central point of the ArgoUML development project. 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 users to be. Some illustrations that do not work well in the other parts of the documentation. This is done as a complement to the other parts. Examples, tours.
The manual and quick-guide 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. Describe how ArgoUML is installed and used. Describe how UML is used with 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 texts within the running ArgoUML Users of ArgoUML. Give a quick help with a specific feature or button. Give short explanations of all commands and actions. A complete set of quick help and explanations.
The FAQ Users of ArgoUML. Members of the users mailing list. Cope for shortcomings in ArgoUML, the help text, the Manual and quick-guide and the web site. 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 Cookbook, the User Manual, and the Quick Guide, are all written in docbook and generated into HTML and PDF during deployment. See Chapter 10, Standards For Documentation Writing for details on how to write these.