Guidelines: Important Decisions in Analysis & Design

Topics

• Decide How to Use Artifacts
• Decide Which Reports to Use
• Identify Configuration Items
• Decide How to Review

Decide How to Use Artifacts

Decide which artifacts to use and how to use each of them. The table below describes which artifacts are mandatory, and which can be used in some cases. The 'tailoring comments' give some guidelines as to how you can tailor each artifact.

For a complete description of each artifact, see Analysis & Design Artifacts.  For a discussion of the advantages and disadvantages of that specific artifact, read the section, "Tailoring" for each artifact.

Tailor each artifact by performing the steps described in "Tailor Artifacts per Workflow" in the Activity: Develop Development Case.

Decide Which Reports to Use

Decide which reports to use by deciding:

• Which "work" reports to use.
• Which reports should be used for final documentation.

You can use the following reports as a starting point:

• Report: Class Report
• Report: Use-Case Realization
• Report: Design-Model Survey

These reports are described in the Report Overview.

Which "Work" Reports to Use

To make reviewing easier, decide which reports to use as temporary "work" reports, extracting information from the design model.

It is recommended that you use Class Report, Use-Case Realization Report, and Design-Model Survey as "work" reports. It may be a good idea to introduce a new report, Package Report, to describe a package, and all its contained classes.

Which Reports to Use for Final Documentation

Decide which, if any, reports you want to capture the final results of Analysis & Design.

At the end of the project you store the results in a configuration management tool. However, your organization may require that the results are captured on paper. If that is the case, you must decide which reports to use to capture the entire design model.

If the predefined reports do not suite your needs, tailor the outline of these reports, or create new reports. For each report decide how the report should be used: "To be skipped", "Casual", "Informal", "Formal-Internal", or "Formal-External". For more details, see the Activity: Develop Development Case.

The following are some examples of different ways to capture the entire design model.

1. One report for the entire design model, and recursively all its contents. This will become one very large document, which will be used as "Formal-Internal".
2. One report for parts of the model, for example for each package. This Package Report, will then describe the package and all contained packages and classes. In addition to this report there must be one report that is a survey of the design model: a Design-Model Survey.

Identify Configuration Items

Read Analysis & Design Artifacts and decide which of the artifacts that should be handled as separate configuration items.

If you decide to not handle an artifact as a separate configuration item, then it should be part of the enclosing artifact. For example, if you decide not to handle each class as a separate configuration item, they should be handled as part of the same configuration item as the enclosing package or subsystem.

It is up to each project to decide what needs to be handled as separate configuration items. It is basically a matter of how you want to control versions of packages and their documentation. Consider how you will work with the design model:

• At what level of granularity do you want to allocate responsibility?
• Will some packages offer optional functionality, or functionality that is interchangeable? Maybe these should be made into separate configuration items.
• Will development be performed incrementally?

The answer to these questions will help you decide the size of the configuration items that constitute the design model.

If you have one person responsible for one package, or if single packages are optional or interchangeable, make each such package into a configuration item.

In a small project it may be enough to let the entire design model be one configuration item. All documents external to the design model must be managed in relation to the corresponding configuration items that contain the classes, subsystems, and packages the documents describe.

When you develop a system incrementally, make sure that you create a baseline at the end of each iteration. In this way, you can control the difference, iteration to iteration.

Decide How to Review

Decide how to review and approve the results of Analysis & Design, and to what extent results should be reviewed.

The advantages and disadvantages of design reviews are:

+ It detects problems that are impossible (or very difficult) to detect in testing. For example, issues of style, and layout. It is a way to enforce a common modeling style, and an opportunity for individuals to learn from each other. It detects defects that otherwise would have been detected during tests later in the project.

- It takes time and resources. It can easily be misused if it is not managed well.

The factors that can be altered are review techniques, resources, and scope. The following are some examples of what you can decide to do on your project:

• Decide that changes local to a subsystem are reviewed only by one peer. The peer, conducts an inspection and hands over the results on paper.
• Decide that some parts of the design should not be reviewed at all. For example, review only some classes for each member of the project, and, then hope that this assures that the style is of similar quality for the rest of their results.
• Decide that the Software Architecture Document should be reviewed by customer, in a separate meeting.
• Decide to use formal review meetings for changes in important interfaces, that is, interfaces that affect the work of several project members.

For more information about reviewing, and different kinds of reviews, see Work Guideline. Reviews.