From site-svn-return-104-apmail-forrest-site-svn-archive=forrest.apache.org@forrest.apache.org Wed Apr 11 02:04:09 2007 Return-Path: Delivered-To: apmail-forrest-site-svn-archive@locus.apache.org Received: (qmail 30186 invoked from network); 11 Apr 2007 02:04:05 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 11 Apr 2007 02:04:04 -0000 Received: (qmail 7696 invoked by uid 500); 11 Apr 2007 02:04:10 -0000 Delivered-To: apmail-forrest-site-svn-archive@forrest.apache.org Received: (qmail 7571 invoked by uid 500); 11 Apr 2007 02:04:10 -0000 Mailing-List: contact site-svn-help@forrest.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@forrest.apache.org Delivered-To: mailing list site-svn@forrest.apache.org Received: (qmail 7480 invoked by uid 99); 11 Apr 2007 02:04:09 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 10 Apr 2007 19:04:09 -0700 X-ASF-Spam-Status: No, hits=-99.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 10 Apr 2007 19:03:58 -0700 Received: by eris.apache.org (Postfix, from userid 65534) id 19CC21A984A; Tue, 10 Apr 2007 19:03:38 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r527368 [4/6] - in /forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo: ./ docs/developer/useCases/ docs/user/useCases/ images/ skin/ skin/images/ svn-log/ useCases/ Date: Wed, 11 Apr 2007 02:03:34 -0000 To: site-svn@forrest.apache.org From: crossley@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070411020338.19CC21A984A@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/user/useCases/useCaseFeatures.source.xml URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/user/useCases/useCaseFeatures.source.xml?view=diff&rev=527368&r1=527367&r2=527368 ============================================================================== --- forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/user/useCases/useCaseFeatures.source.xml (original) +++ forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/user/useCases/useCaseFeatures.source.xml Tue Apr 10 19:03:32 2007 @@ -15,24 +15,27 @@ limitations under the License. --> 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.

- +

+ 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:

- +

+ 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
    • @@ -41,181 +44,198 @@
  • 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 + + 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 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.

- +

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

- - 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 +

+ 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 + + + 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 +
    • 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 +
  • 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 + + 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:

- +

+ 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
    • +
  • 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. +

+ 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 + Request http://localhost:8888/docs/developer/useCases.xml

@@ -223,38 +243,48 @@ 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. - + + 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).

+

+ 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,

+

+ 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:

- +

+ 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
    • @@ -262,27 +292,29 @@
  • 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. +

+ 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 + Request http://localhost:8888/docs/user/useCases.xml

@@ -290,46 +322,60 @@ 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 - + + 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).

+

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

+

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

+

+ 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 @@ -341,30 +387,42 @@

- An XDoc is created that lists the steps in each use case and identifies the status - of each use case. + 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. - + + 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).

+

+ 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,

+

+ 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, +

Modified: forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/images/project.png URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/images/project.png?view=diff&rev=527368&r1=527367&r2=527368 ============================================================================== Binary files - no diff available. Modified: forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/index.html URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/index.html?view=diff&rev=527368&r1=527367&r2=527368 ============================================================================== --- forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/index.html (original) +++ forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/index.html Tue Apr 10 19:03:32 2007 @@ -77,7 +77,7 @@ |breadtrail +-->
- +  
- +  
- - - - - Modified: forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/log.svn.html URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/log.svn.html?view=diff&rev=527368&r1=527367&r2=527368 ============================================================================== --- forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/log.svn.html (original) +++ forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/log.svn.html Tue Apr 10 19:03:32 2007 @@ -77,7 +77,7 @@ |breadtrail +-->
- +  
- +  
- +