Login | Register
My pages Projects Community openCollabNet
8.7. User Manual Plans
Prev Chapter 8. Writing Documentation in the ArgoUML Project Next

8.7. 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.

8.7.1. 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.

8.7.2. Goals for the User Manual

The goals are (in priority order):

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

  2. Descriptive reference material on all components of ArgoUML

  3. Keep boundaries clearly defined, to avoid duplication with the Cookbook, FAQ, Quick Guide, on-line help etc.

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

8.7.2.1. 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.

8.7.3. 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.

8.7.3.1. Tutorial Manual Structure

  1. Introduction

    1. Origins and overview of ArgoUML

    2. Scope of the User Manual. Include cross-reference to other documentation (Cookbook, FAQ, Quick Guide, on-line help, ArgoUML website etc).

    3. 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.

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

  2. UML Based OOA&D

    1. Background to UML — what it is, history etc.

    2. UML based processes for OOA&D

    3. ArgoUML Basics — projects, drawing, exploring, details

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

    5. The Case Study

  3. Requirements Capture

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

  4. Analysis

    1. Concept Class Diagrams

    2. System Sequence Charts and Collaboration Diagrams

    3. System State-chart Diagrams

  5. Design

    1. Class Diagrams for Realization

    2. Sequence Charts and Collaboration Diagrams for Realization

    3. State-chart Diagrams for realization

    4. Package Diagrams

  6. Build

    1. Deployment Diagrams

    2. Code Generation in ArgoUML

8.7.3.2. Reference Manual Structure

  1. 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.

  2. An Index

8.7.4. 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.

8.7.4.1. 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.

  1. Get buy-in for the approach. (Completed)

  2. Agree document structure (broadly). (Completed)

  3. Choose a suitable example to run throughout.

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

  5. Identify all existing sources of material to be reused

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

    1. 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).

    2. User Manual examples

    3. User Manual sections relating to additional ArgoUML cognitive design features.

    4. User Manual sections relating to UML (for readers who don't know UML).

    5. Completion of Reference Manual material.

  7. Create an index. (Completed)

8.7.4.2. Remaining Questions

  1. The current manual shows copyright held by Phillipe, and no legal notice. What is the position of this material? (Solved)

Prev Up Next
8.6. For Emacs Users Home Chapter 9. Processes for the ArgoUML project