Uses Cases for the Use Case management features of org.apache.forrest.plugin.input.projectInfo Write Use Case Documentation

Write semi-structured use case documents so that they can be reused in a variety of ways. This use case describews a process for writing such documents. This document is derived from such a source document.

Justification

A use case describes a unit of work. It is typically used in the design stages of a software project. It is very useful for describing what an applicaiton must do and what patchs through the system can be taken.

By bringing this information together in a semi-structured document we can use it in many different ways. For example:

  • Requirements Documentation
  • Developer Documentation
  • User Documentaiton
  • Functionality Matrices
  • Task Lists
 Create/open a Use Case file In your favourite XML editor either create a new file or open an existing use case file. The default location of these files within a Forrest content object is /content/documentation/useCases/**.xml You have either a blank use case document or an existing one ready for editing. Create a DTD for use case descriptions. Aggregate all documents in the useCases directory to provide ne large document describing all use cases. Create a new use case

A use case is enclosed within a useCase element. Each use case should be given a brief title to describe it.

You have the container for your new use case. Describe the overall objective of the use case

Each use case should be described in terms of:

  • The objective
  • The expected results
  • The justification

This information should be placed in the description element of your use case. This node allows any XDoc markup and therefore you are reasonably free to use whatever formatting or images are needed to convey the important details most efficiently.

You have a use case that is described sufficiently well for an average user of the end system to understand its purpose. Define each step in the Use Case

Each use case will be subdivided into one or more steps that must be carried out in order to complete the task. Each of these steps is defined within a step element which are chilren of a steps element.

Descripbe the step

Each step has a title and a description. The description should provide enough information for a user to complete the task and for a developer to implement support for the user in that task.

In addition each step can be described as required or optional. By default a step is assumed be required. To set it to optional add a required="false" attribute to the step element.

A user will be able to follow instructions on how to carry out the step. Describe the expected results

Provide, within a result a brief description of the expected results from this step. This should summarise what state the application will be in once this use case has been performed.

You will have provided enough information to allow developers to test the functionality and users to identify when a step has been succesfully completed. Add "fixme" notes

A fixme note is enclosed within a fixme element. It describes something that remains to be done within this step. Each fixme has a priority attribute which can take one of of the followin values:

  • Enhancement - a nice to have ehancment that may or may not be implemented.
  • Low - this is considered an important addition to the use case, but everything works without it.
  • High - this is an important addition. Everything works without it, but having this implmeneted would improve the application considerably.
  • Major - this is nor preventing work that utilises the use case, but it is considered a requirement for the next release since it adds key functionlaity.
  • Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP

Although this step is optional, it is good practice to allways add a <fixme priority="blocker">Not yet implemented</fixme> element to all new steps. This is becuase these nodes will be used to build a functionality matrix later on.

Users will be able to understand to what degree a step is implemented and developers will be able to see what remains to be done. All fixmes to link to an issue tracker entry Add alternatives

Sometimes there will be alternative paths through each step. These can be described in an alternatives element that allows free-form XDoc content. However, please be careful, if an alternative is more than a simple variation you may want to consider a whole new use case for the alternative.

Minor variations in the path through a use case will be documented for your users. Write Implementation Notes

Developer implementation notes for each of the steps should be added either when writing the initial use case or later during the development phases of the use case. These notes are for technical readers and are intended to help those who come after the initial author to get a starting point when inspecting how a feature is implemented. It is not intended that these notes will contain full implementation details, only an overview should be provided.

A technical reader will be able to gain a baisc understanding of how each step is implemented in the application. Generate Use Case Documentation for Developers

Generate a complete list of all use cases for a project in a format useful to developers of the application. This list is to include:

  • a description of the use case
  • a summary of each of the steps involved
  • full details of each of the steps
  • a description of the expected outcome of each step
  • details of common alternatives in each step
  • implementation notes for each step
Justification

A use case describes a unit of work. It is typically used in the design stages of a software project, however, they can often be useful in creating user documentaiton. Especially when they describe user interface functionality.

Unfortunately this use case document does not currently cover all functions of the plugin since this functionlaity was added after many other features. Whilst you are exploring this feature, why not add a use case to the plugin and submit a patch so that those coming after you can enjoy more complete documentation.
Make HTTP request

Request http://localhost:8888/docs/developer/useCases.xml

An XDoc is created that describes the use cases

Make the summary optional - already added $includeImplementationNotes parameter to stylesheet. Need to pass value form sitemap.

Depending on what plugins are available within your running instance of Forrest you will be able to request different output formats as per the usual Forrest usage. For example requesting a http://localhost:8888/docs/developer/useCases.html will generate the HTML document, whilst http://localhost:8888/docs/developer/useCases.pdf will generate the PDF document (as long as you have the relevant plugins installed).

The source document for use cases is, by default, called useCases.xml and is located in the root of the projects xdocs directory.

The URL space docs/**/useCases.xml is reserved for the projectInfo plugin. A request to /docs/developer/useCases.xml results in the useCases.xml file being translated into an XDoc as per the usual forrest processing. See the input.xmap file fo this plugin,

Generate Use Case Documentation for Users

Generate a complete list of all use cases for a project. This list is to include:

  • a description of the use case
  • a summary of each of the steps involved
  • full details of each of the steps
  • a description of the expected outcome of each step
  • details of common alternatives in each step
Justification

A use case describes a unit of work. It is typically used in the design stages of a software project, however, they can often be useful in creating user documentaiton. Especially when they describe user interface functionality.

Unfortunately the use case document does not currently cover all functions of the plugin since this functionlaity was added after many other features. Whilst you are exploring this feature, why not add a use case to the plugin and submit a patch so that those coming after you can enjoy more complete documentation.
Make HTTP request

Request http://localhost:8888/docs/user/useCases.xml

An XDoc is created that describes the use cases

Enable the retrieval of a specific use case rather than all at once. Make the summary optional - there is a switch in the XSL for this, just need to pass a property from the XMAP

Depending on what plugins are available within your running instance of Forrest you will be able to request different output formats as per the usual Forrest usage. For example requesting a http://localhost:8888/docs/user/useCases.html will generate the HTML document, whilst http://localhost:8888/docs/user/useCases.pdf will generate the PDF document (as long as you have the relevant plugins installed).

The source document for use cases is, by default, called useCases.xml and is located in the root of the projects xdocs directory.

The URL space docs/**/useCases.xml is reserved for the projectInfo plugin. A request to /docs/user/useCases.xml results in the useCases.xml file being translated into an XDoc as per the usual forrest processing, see input.xmap for more details.

Generate a Functionality Matrix

If a use case document is correcly marked up with fixme elements it is possible to create a functionality matrix for each use case. This will show how complete the implementation of a use case is.

A table can be created which shows each of the steps in a use case, each step can be given a count for the bumber of fixme items outstanding on each of the steps. Furthermore, since each fixme is given a priority we can clearly indicate which use cases are operational an hich are not.

Make HTTP request

Request http://localhost:8888/docs/developer/featureMatrix/useCases.xml

An XDoc is created that lists the steps in each use case and identifies the status of each use case.

Not Implemented Yet - although the user and dev use case documents do show the status of each step in the details table and implementation notes.

Depending on what plugins are available within your running instance of Forrest you will be able to request different output formats as per the usual Forrest usage. For example requesting a http://localhost:8888/docs/developer/featureMatrix/useCases.html will generate the HTML document, whilst http://localhost:8888/docs/developer/featureMatrix/useCases.pdf will generate the PDF document (as long as you have the relevant plugins installed).

The source document for use cases is, by default, called useCases.xml and is located in the root of the projects xdocs directory.

The URL space docs/**/useCases.xml is reserved for the projectInfo plugin. A request to /docs/developer/featureMatrix/useCases.xml results in the useCases.xml file being translated into an XDoc as per the usual forrest processing. See the input.xmap file fo this plugin,