argouml Wiki: User Manual Plans

The User Manual is a very separate part of the ArgoUML project. It is independent of the rest of the project w.r.t. updates, deliveries, ambition and plans. The development of the User Manual is more or less a project of its own. Since autumn 2003 we also have an appointed sub project leader for this. This Responsibility is called Editor for the User Manual and Quick Guide and is held by Michiel van der Wulp.

This section describes the ambition and plans for the User Manual.

Target Audiences for the User Manual

Target audiences are the following:

Experienced users of UML in OOA&D (perhaps with other tools) who wish to transfer to ArgoUML.

Designers who know OOA&D, and wish to adopt a UML based process.

In the longer term it would be desirable to also target the following.

Those who are learning design and wish to start with a UML based OOA&D process.

People interested in modularized code design with a GUI.

Goals for the User Manual

The goals are (in priority order):

A tutorial style explanation of ArgoUML in the context of an OOA&D process.

I (probably Jeremy Bennet in 2002?) think the existing User Manual is a good start particularly towards the second of these goals.

What the User Manual is not (currently)

To keep the effort feasible the user manual should avoid the following (at least initially).

Providing a quick overview—the Quick Guide already does this.

Listing all the errors and what they mean. The help system does this—one day the manual will link to that.

Explaining the internal workings of ArgoUML. The cookbook, combined with Jason Robbins dissertation is already a good start for this.

Suggested Manual Structure

Here are my (Jeremy Bennet, 2002?) thoughts. I think the user manual is really a set of two books, the tutorial manual (corresponding to Part I of the current manual), and the reference manual (Part II of the current manual)

I (Jeremy Bennet, 2002?) suggest that the tutorial book be based around an OOA&D process (any preferences), and that each UML concept is introduced with each step of the process, followed by an explanation of how to do it under ArgoUML. A simple case study will be needed throughout.

Tutorial Manual Structure

Overview of the User Manual. Explains that ArgoUML will be explained in the context of an OOA&D process, and with an example running through.

Assumptions. At this stage assume the user knows OOA&D, but not UML.

UML Based OOA&D

Background to UML — what it is, history etc.

UML based processes for OOA&D

ArgoUML Basics — projects, drawing, exploring, details

What ArgoUML has that other tools are missing (critics, to-do list, based on cognitive psychology theory).

The Case Study

Requirements Capture

Use Case Diagrams (this section will be relatively large, because its the first time we use ArgoUML to create something).

Analysis

Concept Class Diagrams

System Sequence Charts and Collaboration Diagrams

System State-chart Diagrams

Design

Class Diagrams for Realization

Sequence Charts and Collaboration Diagrams for Realization

State-chart Diagrams for realization

Package Diagrams

Build

Deployment Diagrams

Code Generation in ArgoUML

Reference Manual Structure

Material on each of the diagram types, each of the artifacts that can appear on the diagrams and details of the features of each artifact type.

An Index

Actions, Priorities and Questions

This section has two serious problems. Firstly, I (Linus Tolke, 2004) think Jeremy Bennet wrote this and then started and has completed a lot of the items so they could be checked off. Secondly, keeping this list in a docbook document is not a good idea. It is better to make issues in Issuezilla of it that can be individually closed. I (Linus Tolke 2004) will make issues of the things I think are left to be done and remove this section (unless someone beats me to it). I (Linus Tolke 2006) am still hoping that someone will beat me to it.

Actions and priorities

Here's my first call for what needs to be done in priority order. From the comments made over the last few days I think the first 5 items won't take very long, meaning effort can concentrate on the main stuff.

Get buy-in for the approach. (Completed)

Agree document structure (broadly). (Completed)

Choose a suitable example to run throughout.

Break into several files (XML entities) to make the manual more manageable. (Completed and then joined again.)

Identify all existing sources of material to be reused

Get writing! I (Jeremy Bennet 2002?) suggest the priorities here are:

User Manual sections relating to ArgoUML diagrams and artifacts (assume the reader knows UML already, and allows a quick advance by pulling together a lot of existing material).