forrest-site-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r527368 [2/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 GMT
Modified: forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/developer/useCases/useCaseFeatures.html
URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/developer/useCases/useCaseFeatures.html?view=diff&rev=527368&r1=527367&r2=527368
==============================================================================
--- forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/developer/useCases/useCaseFeatures.html (original)
+++ forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/developer/useCases/useCaseFeatures.html Tue Apr 10 19:03:32 2007
@@ -77,7 +77,7 @@
     |breadtrail
     +-->
 <div class="breadtrail">
-             
+
              &nbsp;
            </div>
 <!--+
@@ -238,16 +238,24 @@
 <div class="section">
 <a name="N1000B"></a><a name="Write+Use+Case+Documentation"></a>
 <h3 class="underlined_5">Write Use Case Documentation</h3>
-<p>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 <a href="useCaseFeatures.source.xml">source document</a>.</p>
+<p>
+        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
+        <a href="useCaseFeatures.source.xml">source document</a>.
+      </p>
 <a name="N10018"></a><a name="Justification"></a>
 <h4>Justification</h4>
-<p>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.</p>
-<p>By bringing this information together in a semi-structured document we can use it in many
-        different ways. For example:</p>
+<p>
+          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.
+        </p>
+<p>
+          By bringing this information together in a semi-structured document we
+          can use it in many different ways. For example:
+        </p>
 <ul>
           
 <li>Requirements Documentation</li>
@@ -268,43 +276,35 @@
 <li>
 <strong>Create/open a Use Case file</strong>
 </li>
-
       
 <li>
 <strong>Create a new use case</strong>
 </li>
-
-        
+      
 <li>
 <strong>Describe the overall objective of the use case</strong>
 </li>
-
-        
+      
 <li>
 <strong>Define each step in the Use Case</strong>
 </li>
-
-        
+      
 <li>
 <strong>Descripbe the step</strong>
 </li>
-
-        
+      
 <li>
 <strong>Describe the expected results</strong>
 </li>
-
-        
+      
 <li>
 <strong>Add "fixme" notes</strong> (Optional)</li>
-
-        
+      
 <li>
 <strong>Add alternatives</strong> (Optional)</li>
-        
-        
+      
 <li>
-<strong>Write Implementation Notes</strong> (Optional)</li>          
+<strong>Write Implementation Notes</strong> (Optional)</li>
     
 </ol>
 <a name="N10065"></a><a name="Details"></a>
@@ -315,152 +315,172 @@
 </tr>
       
 <tr>
-<td>1. Create/open a Use Case file</td><td>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 <span class="codefrag">/content/documentation/useCases/**.xml</span>
+<td>1. Create/open a Use Case file</td><td>
+          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
+          <span class="codefrag">/content/documentation/useCases/**.xml</span>
         </td><td>You have either a blank use case document or an existing one ready for editing.</td><td>
            Implemented with fixmes:-<br>
          High: 1<br>
 </td>
 </tr>
-
       
 <tr>
 <td>2. Create a new use case</td><td>
           
-<p>A use case is enclosed within a <span class="codefrag">useCase</span> element.
-          Each use case should be given a brief <span class="codefrag">title</span> to describe it.</p>
-
+<p>
+            A use case is enclosed within a <span class="codefrag">useCase</span> element. Each
+            use case should be given a brief <span class="codefrag">title</span> to describe it.
+          </p>
         
 </td><td>You have the container for your new use case.</td><td>Implemented</td>
 </tr>
-
-        
+      
 <tr>
 <td>3. Describe the overall objective of the use case</td><td>
-            
-<p>Each use case should be described in terms of:</p>
-            
+          
+<p>
+            Each use case should be described in terms of:
+          </p>
+          
 <ul>
-              
+            
 <li>The objective</li>
-              
+            
 <li>The expected results</li>
-              
-<li>The justification</li>
             
+<li>The justification</li>
+          
 </ul>
-            
-<p>This information should be placed in the <span class="codefrag">description</span> 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.</p>
           
+<p>
+            This information should be placed in the <span class="codefrag">description</span>
+            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.
+          </p>
+        
 </td><td>You have a use case that is described sufficiently well for an average user of the end system
         to understand its purpose.</td><td>Implemented</td>
 </tr>
-
-        
+      
 <tr>
 <td>4. Define each step in the Use Case</td><td>
-            
-<p>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 <span class="codefrag">step</span>
-          element which are chilren of a <span class="codefrag">steps</span> element.</p>
           
+<p>
+            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 <span class="codefrag">step</span> element which are chilren of a
+            <span class="codefrag">steps</span> element.
+          </p>
+        
 </td><td></td><td>Implemented</td>
 </tr>
-
-        
+      
 <tr>
 <td>5. Descripbe the step</td><td>
-            
-<p>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.</p>
+          
+<p>
+            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.
+          </p>
 
-            
-<p>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 <span class="codefrag">required="false"</span> attribute to the
-            <span class="codefrag">step</span> element.</p>
           
+<p>
+            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
+            <span class="codefrag">required="false"</span> attribute to the <span class="codefrag">step</span>
+            element.
+          </p>
+        
 </td><td>A user will be able to follow instructions on how to carry out the step.</td><td>Implemented</td>
 </tr>
-
-        
+      
 <tr>
 <td>6. Describe the expected results</td><td>
-            
-<p>Provide, within a <span class="codefrag">result</span> 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.</p>
           
+<p>
+            Provide, within a <span class="codefrag">result</span> 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.
+          </p>
+        
 </td><td>You will have provided enough information to allow developers to test the functionality and
           users to identify when a step has been succesfully completed.</td><td>Implemented</td>
 </tr>
-
-        
+      
 <tr>
 <td>7. Add "fixme" notes<br>(Optional)</td><td>
-            
-<p>A fixme note is enclosed within a <span class="codefrag">fixme</span> 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:</p>
-
-            
+          
+<p>
+            A fixme note is enclosed within a <span class="codefrag">fixme</span> 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:
+          </p>
+          
 <ul>
-              
+            
 <li>Enhancement - a nice to have ehancment that may or may not be implemented.</li>
-              
+            
 <li>Low - this is considered an important addition to the use case, but everything works without it.</li>
-              
+            
 <li>High - this is an important addition. Everything works without it, but having this implmeneted would
               improve the application considerably.</li>
-              
+            
 <li>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.</li>
-              
-<li>Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP</li>
             
+<li>Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP</li>
+          
 </ul>
-
-            
-<p>Although this step is optional, it is good practice to allways add a 
-            <span class="codefrag">&lt;fixme priority="blocker"&gt;Not yet implemented&lt;/fixme&gt;</span>
-            element to all new steps. This is becuase these nodes will be used to build a 
-            functionality matrix later on.</p>
           
+<p>
+            Although this step is optional, it is good practice to allways add a
+            <span class="codefrag">&lt;fixme priority="blocker"&gt;Not yet
+            implemented&lt;/fixme&gt;</span> element to all new steps. This is
+            becuase these nodes will be used to build a functionality matrix
+            later on.
+          </p>
+        
 </td><td>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.</td><td>
            Implemented with fixmes:-<br>
 </td>
 </tr>
-
-        
+      
 <tr>
 <td>8. Add alternatives<br>(Optional)</td><td>
-            
-<p>Sometimes there will be alternative paths through each step. These can be described in an
-            <span class="codefrag">alternatives</span> 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.</p>
           
+<p>
+            Sometimes there will be alternative paths through each step. These
+            can be described in an <span class="codefrag">alternatives</span> 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.
+          </p>
+        
 </td><td>Minor variations in the path through a use case will be documented for your users.</td><td>Implemented</td>
 </tr>
-        
-        
+      
 <tr>
 <td>9. Write Implementation Notes<br>(Optional)</td><td>
-            
-<p>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.</p>
           
+<p>
+            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.
+          </p>
+        
 </td><td>A technical reader will be able to gain a baisc understanding of how each step is implemented in the 
           application.</td><td>Implemented</td>
-</tr>          
+</tr>
     
 </table>
 <a name="N1013A"></a><a name="Implementation+Notes"></a>
@@ -475,73 +495,69 @@
 <br>
 <div class="fixme">
 <div class="label">Fixme (High)</div>
-<div class="content">Aggregate all documents in the useCases directory to provide
-        ne large document describing all use cases.</div>
+<div class="content">
+          Aggregate all documents in the useCases directory to provide ne large
+          document describing all use cases.
+        </div>
 </div>
 </td>
 </tr>
-
       
 <tr>
 <td>2. Create a new use case</td><td>
 <br>
 </td>
 </tr>
-
-        
+      
 <tr>
 <td>3. Describe the overall objective of the use case</td><td>
 <br>
 </td>
 </tr>
-
-        
+      
 <tr>
 <td>4. Define each step in the Use Case</td><td>
 <br>
 </td>
 </tr>
-
-        
+      
 <tr>
 <td>5. Descripbe the step</td><td>
 <br>
 </td>
 </tr>
-
-        
+      
 <tr>
 <td>6. Describe the expected results</td><td>
 <br>
 </td>
 </tr>
-
-        
+      
 <tr>
 <td>7. Add "fixme" notes</td><td>
 <br>
 </td>
 </tr>
-
-        
+      
 <tr>
 <td>8. Add alternatives</td><td>
 <br>
 </td>
 </tr>
-        
-        
+      
 <tr>
 <td>9. Write Implementation Notes</td><td>
 <br>
 </td>
-</tr>          
+</tr>
     
 </table>
 <a name="N1017F"></a><a name="Generate+Use+Case+Documentation+for+Developers"></a>
 <h3 class="underlined_5">Generate Use Case Documentation for Developers</h3>
-<p>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:</p>
+<p>
+        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:
+      </p>
 <ul>
         
 <li>a description of the use case</li>
@@ -554,20 +570,26 @@
         
 <li>details of common alternatives in each step</li>
         
-<li>implementation notes for each step</li> 
+<li>implementation notes for each step</li>
       
 </ul>
 <a name="N1019D"></a><a name="Justification-N1019D"></a>
 <h4>Justification</h4>
-<p>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.</p>
+<p>
+          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.
+        </p>
 <div class="warning">
 <div class="label">Warning</div>
-<div class="content">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.</div>
+<div class="content">
+          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.
+        </div>
 </div>
 <a name="N101AA"></a><a name="Summary-N101AA"></a>
 <h4>Summary</h4>
@@ -589,8 +611,7 @@
 <td>1. Make HTTP request</td><td>
           
 <p>
-            Request
-            http://localhost:8888/docs/developer/useCases.xml
+            Request http://localhost:8888/docs/developer/useCases.xml
           </p>
         
 </td><td>
@@ -616,19 +637,28 @@
 <tr>
 <td>1. Make HTTP request</td><td>
             
-<p>The source document for use cases is, by default, called <span class="codefrag">useCases.xml</span> and is
-            located in the root of the projects xdocs directory.</p>
+<p>
+              The source document for use cases is, by default, called
+              <span class="codefrag">useCases.xml</span> and is located in the root of the
+              projects xdocs directory.
+            </p>
 
             
-<p>The URL space <span class="codefrag">docs/**/useCases.xml</span> 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,</p>
+<p>
+              The URL space <span class="codefrag">docs/**/useCases.xml</span> 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,
+            </p>
           
 <br>
 <div class="fixme">
 <div class="label">Fixme (High)</div>
-<div class="content">Make the summary optional - already added 
-        $includeImplementationNotes parameter to stylesheet. Need to pass value form sitemap.</div>
+<div class="content">
+          Make the summary optional - already added $includeImplementationNotes
+          parameter to stylesheet. Need to pass value form sitemap.
+        </div>
 </div>
 </td>
 </tr>
@@ -636,7 +666,10 @@
 </table>
 <a name="N101F9"></a><a name="Generate+Use+Case+Documentation+for+Users"></a>
 <h3 class="underlined_5">Generate Use Case Documentation for Users</h3>
-<p>Generate a complete list of all use cases for a project. This list is to include:</p>
+<p>
+        Generate a complete list of all use cases for a project. This list is to
+        include:
+      </p>
 <ul>
         
 <li>a description of the use case</li>
@@ -652,15 +685,21 @@
 </ul>
 <a name="N10214"></a><a name="Justification-N10214"></a>
 <h4>Justification</h4>
-<p>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.</p>
+<p>
+          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.
+        </p>
 <div class="warning">
 <div class="label">Warning</div>
-<div class="content">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.</div>
+<div class="content">
+          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.
+        </div>
 </div>
 <a name="N10221"></a><a name="Summary-N10221"></a>
 <h4>Summary</h4>
@@ -682,8 +721,7 @@
 <td>1. Make HTTP request</td><td>
           
 <p>
-            Request
-            http://localhost:8888/docs/user/useCases.xml
+            Request http://localhost:8888/docs/user/useCases.xml
           </p>
         
 </td><td>
@@ -710,23 +748,33 @@
 <tr>
 <td>1. Make HTTP request</td><td>
             
-<p>The source document for use cases is, by default, called <span class="codefrag">useCases.xml</span> and is
-            located in the root of the projects xdocs directory.</p>
+<p>
+              The source document for use cases is, by default, called
+              <span class="codefrag">useCases.xml</span> and is located in the root of the
+              projects xdocs directory.
+            </p>
 
             
-<p>The URL space <span class="codefrag">docs/**/useCases.xml</span> 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.</p>
+<p>
+              The URL space <span class="codefrag">docs/**/useCases.xml</span> 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.
+            </p>
           
 <br>
 <div class="fixme">
 <div class="label">Fixme (High)</div>
-<div class="content">Enable the retrieval of a specific use case rather than all at once.</div>
+<div class="content">
+          Enable the retrieval of a specific use case rather than all at once.
+        </div>
 </div>
 <div class="fixme">
 <div class="label">Fixme (Low)</div>
-<div class="content">Make the summary optional - there is a switch in the XSL for this, just need to pass a property
-        from the XMAP</div>
+<div class="content">
+          Make the summary optional - there is a switch in the XSL for this,
+          just need to pass a property from the XMAP
+        </div>
 </div>
 </td>
 </tr>
@@ -734,13 +782,18 @@
 </table>
 <a name="N10275"></a><a name="Generate+a+Functionality+Matrix"></a>
 <h3 class="underlined_5">Generate a Functionality Matrix</h3>
-<p>If a use case document is correcly marked up with <span class="codefrag">fixme</span> 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.</p>
-<p>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
-      <span class="codefrag">fixme</span> is given a priority we can clearly indicate which use cases are operational an 
-      hich are not.</p>
+<p>
+        If a use case document is correcly marked up with <span class="codefrag">fixme</span>
+        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.
+      </p>
+<p>
+        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 <span class="codefrag">fixme</span> is given a
+        priority we can clearly indicate which use cases are operational an hich
+        are not.
+      </p>
 <a name="N10287"></a><a name="Summary-N10287"></a>
 <h4>Summary</h4>
 <ol class="steps">
@@ -768,14 +821,16 @@
 </td><td>
           
 <p>
-            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.
           </p>
         
 </td><td>
 <div class="warning">
 <div class="label">Warning</div>
-<div class="content">Not Implemented</div>
+<div class="content">
+              Not Implemented
+            </div>
 </div>
          Blockers: 1<br>
 </td>
@@ -792,19 +847,29 @@
 <tr>
 <td>1. Make HTTP request</td><td>
             
-<p>The source document for use cases is, by default, called <span class="codefrag">useCases.xml</span> and is
-            located in the root of the projects xdocs directory.</p>
+<p>
+              The source document for use cases is, by default, called
+              <span class="codefrag">useCases.xml</span> and is located in the root of the
+              projects xdocs directory.
+            </p>
 
             
-<p>The URL space <span class="codefrag">docs/**/useCases.xml</span> 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,</p>
+<p>
+              The URL space <span class="codefrag">docs/**/useCases.xml</span> 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,
+            </p>
           
 <br>
 <div class="fixme">
 <div class="label">Fixme (Blocker)</div>
-<div class="content">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.</div>
+<div class="content">
+          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.
+        </div>
 </div>
 </td>
 </tr>

Modified: forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/developer/useCases/useCaseFeatures.source.xml
URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/developer/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/developer/useCases/useCaseFeatures.source.xml (original)
+++ forrest/site/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/docs/developer/useCases/useCaseFeatures.source.xml Tue Apr 10 19:03:32 2007
@@ -15,24 +15,27 @@
   limitations under the License.
 --><useCases>
   <title>Uses Cases for the Use Case management features of org.apache.forrest.plugin.input.projectInfo</title>
-
   <useCase>
     <title>Write Use Case Documentation</title>
     <description>
-      <p>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 <a href="useCaseFeatures.source.xml">source document</a>.</p>
-
+      <p>
+        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
+        <a href="useCaseFeatures.source.xml">source document</a>.
+      </p>
       <section>
         <title>Justification</title>
-
-        <p>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.</p>
-
-        <p>By bringing this information together in a semi-structured document we can use it in many
-        different ways. For example:</p>
-
+        <p>
+          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.
+        </p>
+        <p>
+          By bringing this information together in a semi-structured document we
+          can use it in many different ways. For example:
+        </p>
         <ul>
           <li>Requirements Documentation</li>
           <li>Developer Documentation</li>
@@ -41,181 +44,198 @@
           <li>Task Lists</li>
         </ul>
       </section>
-      
     </description>
-
     <steps>
       <step>
         <title>Create/open a Use Case file</title>
-        <description>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 <code>/content/documentation/useCases/**.xml</code>
+        <description>
+          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
+          <code>/content/documentation/useCases/**.xml</code>
         </description>
         <result>You have either a blank use case document or an existing one ready for editing.</result>
-
-        <fixme priority="Medium">Create a DTD for use case descriptions.</fixme>
-        <fixme priority="High">Aggregate all documents in the useCases directory to provide
-        ne large document describing all use cases.</fixme>
+        <fixme priority="Medium">
+          Create a DTD for use case descriptions.
+        </fixme>
+        <fixme priority="High">
+          Aggregate all documents in the useCases directory to provide ne large
+          document describing all use cases.
+        </fixme>
       </step>
-
       <step>
         <title>Create a new use case</title>
         <description>
-          <p>A use case is enclosed within a <code>useCase</code> element.
-          Each use case should be given a brief <code>title</code> to describe it.</p>
-
+          <p>
+            A use case is enclosed within a <code>useCase</code> element. Each
+            use case should be given a brief <code>title</code> to describe it.
+          </p>
         </description>
-
         <result>You have the container for your new use case.</result>
       </step>
-
-        <step>
-          <title>Describe the overall objective of the use case</title>
-          <description>
-            <p>Each use case should be described in terms of:</p>
-            <ul>
-              <li>The objective</li>
-              <li>The expected results</li>
-              <li>The justification</li>
-            </ul>
-            <p>This information should be placed in the <code>description</code> 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.</p>
-          </description>
-
-          <result>You have a use case that is described sufficiently well for an average user of the end system
+      <step>
+        <title>Describe the overall objective of the use case</title>
+        <description>
+          <p>
+            Each use case should be described in terms of:
+          </p>
+          <ul>
+            <li>The objective</li>
+            <li>The expected results</li>
+            <li>The justification</li>
+          </ul>
+          <p>
+            This information should be placed in the <code>description</code>
+            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.
+          </p>
+        </description>
+        <result>You have a use case that is described sufficiently well for an average user of the end system
         to understand its purpose.</result>
-        </step>
-
-        <step>
-          <title>Define each step in the Use Case</title>
-          <description>
-            <p>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 <code>step</code>
-          element which are chilren of a <code>steps</code> element.</p>
-          </description>
-        </step>
-
-        <step>
-          <title>Descripbe the step</title>
-          <description>
-            <p>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.</p>
-
-            <p>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 <code>required="false"</code> attribute to the
-            <code>step</code> element.</p>
-          </description>
-
-          <result>A user will be able to follow instructions on how to carry out the step.</result>
-        </step>
+      </step>
+      <step>
+        <title>Define each step in the Use Case</title>
+        <description>
+          <p>
+            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 <code>step</code> element which are chilren of a
+            <code>steps</code> element.
+          </p>
+        </description>
+      </step>
+      <step>
+        <title>Descripbe the step</title>
+        <description>
+          <p>
+            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.
+          </p>
 
-        <step>
-          <title>Describe the expected results</title>
-          <description>
-            <p>Provide, within a <code>result</code> 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.</p>
-          </description>
-          <result>You will have provided enough information to allow developers to test the functionality and
+          <p>
+            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
+            <code>required="false"</code> attribute to the <code>step</code>
+            element.
+          </p>
+        </description>
+        <result>A user will be able to follow instructions on how to carry out the step.</result>
+      </step>
+      <step>
+        <title>Describe the expected results</title>
+        <description>
+          <p>
+            Provide, within a <code>result</code> 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.
+          </p>
+        </description>
+        <result>You will have provided enough information to allow developers to test the functionality and
           users to identify when a step has been succesfully completed.</result>
-        </step>
-
-        <step required="false">
-          <title>Add "fixme" notes</title>
-          <description>
-            <p>A fixme note is enclosed within a <code>fixme</code> 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:</p>
-
-            <ul>
-              <li>Enhancement - a nice to have ehancment that may or may not be implemented.</li>
-              <li>Low - this is considered an important addition to the use case, but everything works without it.</li>
-              <li>High - this is an important addition. Everything works without it, but having this implmeneted would
+      </step>
+      <step required="false">
+        <title>Add "fixme" notes</title>
+        <description>
+          <p>
+            A fixme note is enclosed within a <code>fixme</code> 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:
+          </p>
+          <ul>
+            <li>Enhancement - a nice to have ehancment that may or may not be implemented.</li>
+            <li>Low - this is considered an important addition to the use case, but everything works without it.</li>
+            <li>High - this is an important addition. Everything works without it, but having this implmeneted would
               improve the application considerably.</li>
-              <li>Major - this is nor preventing work that utilises the use case, but it is considered a requirement
+            <li>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.</li>
-              <li>Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP</li>
-            </ul>
-
-            <p>Although this step is optional, it is good practice to allways add a 
-            <code>&lt;fixme priority="blocker"&gt;Not yet implemented&lt;/fixme&gt;</code>
-            element to all new steps. This is becuase these nodes will be used to build a 
-            functionality matrix later on.</p>
-          </description>
-
-          <result>Users will be able to understand to what degree a step is implemented and developers will be able to 
+            <li>Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP</li>
+          </ul>
+          <p>
+            Although this step is optional, it is good practice to allways add a
+            <code>&lt;fixme priority="blocker"&gt;Not yet
+            implemented&lt;/fixme&gt;</code> element to all new steps. This is
+            becuase these nodes will be used to build a functionality matrix
+            later on.
+          </p>
+        </description>
+        <result>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.</result>
-          
-          <fixme priority="enhancement">All fixmes to link to an issue tracker entry</fixme>
-        </step>
-
-        <step required="false">
-          <title>Add alternatives</title>
-          <description>
-            <p>Sometimes there will be alternative paths through each step. These can be described in an
-            <code>alternatives</code> 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.</p>
-          </description>
-
-          <result>Minor variations in the path through a use case will be documented for your users.</result>
-        </step>
-        
-        <step required="false">
-          <title>Write Implementation Notes</title>
-          <description>
-            <p>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.</p>
-          </description>
-          
-          <result>A technical reader will be able to gain a baisc understanding of how each step is implemented in the 
+        <fixme priority="enhancement">
+          All fixmes to link to an issue tracker entry
+        </fixme>
+      </step>
+      <step required="false">
+        <title>Add alternatives</title>
+        <description>
+          <p>
+            Sometimes there will be alternative paths through each step. These
+            can be described in an <code>alternatives</code> 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.
+          </p>
+        </description>
+        <result>Minor variations in the path through a use case will be documented for your users.</result>
+      </step>
+      <step required="false">
+        <title>Write Implementation Notes</title>
+        <description>
+          <p>
+            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.
+          </p>
+        </description>
+        <result>A technical reader will be able to gain a baisc understanding of how each step is implemented in the 
           application.</result>
-        </step>          
+      </step>
     </steps>
   </useCase>
-
   <useCase status="In Progress" owner="open">
     <title>Generate Use Case Documentation for Developers</title>
-
     <description>
-      <p>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:</p>
-
+      <p>
+        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:
+      </p>
       <ul>
         <li>a description of the use case</li>
         <li>a summary of each of the steps involved</li>
         <li>full details of each of the steps</li>
         <li>a description of the expected outcome of each step</li>
         <li>details of common alternatives in each step</li>
-        <li>implementation notes for each step</li> 
+        <li>implementation notes for each step</li>
       </ul>
-
       <section>
         <title>Justification</title>
-        <p>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.</p>
-
-        <warning>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.</warning>
+        <p>
+          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.
+        </p>
+        <warning>
+          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.
+        </warning>
       </section>
     </description>
-
     <steps>
       <step>
         <title>Make HTTP request</title>
         <description>
           <p>
-            Request
-            http://localhost:8888/docs/developer/useCases.xml
+            Request http://localhost:8888/docs/developer/useCases.xml
           </p>
         </description>
         <result>
@@ -223,38 +243,48 @@
             An XDoc is created that describes the use cases
           </p>
         </result>
-
-        <fixme priority="High">Make the summary optional - already added 
-        $includeImplementationNotes parameter to stylesheet. Need to pass value form sitemap.</fixme>
-        
+        <fixme priority="High">
+          Make the summary optional - already added $includeImplementationNotes
+          parameter to stylesheet. Need to pass value form sitemap.
+        </fixme>
         <alternatives>
-          <p>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).</p>
+          <p>
+            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).
+          </p>
         </alternatives>
-
         <implementation>
           <description>
-            <p>The source document for use cases is, by default, called <code>useCases.xml</code> and is
-            located in the root of the projects xdocs directory.</p>
-
-            <p>The URL space <code>docs/**/useCases.xml</code> 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,</p>
+            <p>
+              The source document for use cases is, by default, called
+              <code>useCases.xml</code> and is located in the root of the
+              projects xdocs directory.
+            </p>
+
+            <p>
+              The URL space <code>docs/**/useCases.xml</code> 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,
+            </p>
           </description>
         </implementation>
       </step>
     </steps>
   </useCase>
-  
   <useCase status="In Progress" owner="open">
     <title>Generate Use Case Documentation for Users</title>
-
     <description>
-      <p>Generate a complete list of all use cases for a project. This list is to include:</p>
-
+      <p>
+        Generate a complete list of all use cases for a project. This list is to
+        include:
+      </p>
       <ul>
         <li>a description of the use case</li>
         <li>a summary of each of the steps involved</li>
@@ -262,27 +292,29 @@
         <li>a description of the expected outcome of each step</li>
         <li>details of common alternatives in each step</li>
       </ul>
-
       <section>
         <title>Justification</title>
-        <p>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.</p>
-
-        <warning>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.</warning>
+        <p>
+          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.
+        </p>
+        <warning>
+          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.
+        </warning>
       </section>
     </description>
-
     <steps>
       <step>
         <title>Make HTTP request</title>
         <description>
           <p>
-            Request
-            http://localhost:8888/docs/user/useCases.xml
+            Request http://localhost:8888/docs/user/useCases.xml
           </p>
         </description>
         <result>
@@ -290,46 +322,60 @@
             An XDoc is created that describes the use cases
           </p>
         </result>
-
-        <fixme priority="High">Enable the retrieval of a specific use case rather than all at once.</fixme>
-        <fixme priority="Low">Make the summary optional - there is a switch in the XSL for this, just need to pass a property
-        from the XMAP</fixme>
-        
+        <fixme priority="High">
+          Enable the retrieval of a specific use case rather than all at once.
+        </fixme>
+        <fixme priority="Low">
+          Make the summary optional - there is a switch in the XSL for this,
+          just need to pass a property from the XMAP
+        </fixme>
         <alternatives>
-          <p>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).</p>
+          <p>
+            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).
+          </p>
         </alternatives>
-
         <implementation>
           <description>
-            <p>The source document for use cases is, by default, called <code>useCases.xml</code> and is
-            located in the root of the projects xdocs directory.</p>
-
-            <p>The URL space <code>docs/**/useCases.xml</code> 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.</p>
+            <p>
+              The source document for use cases is, by default, called
+              <code>useCases.xml</code> and is located in the root of the
+              projects xdocs directory.
+            </p>
+
+            <p>
+              The URL space <code>docs/**/useCases.xml</code> 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.
+            </p>
           </description>
         </implementation>
       </step>
     </steps>
   </useCase>
-  
   <useCase status="In Progress">
     <title>Generate a Functionality Matrix</title>
     <description>
-      <p>If a use case document is correcly marked up with <code>fixme</code> 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.</p>
-      
-      <p>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
-      <code>fixme</code> is given a priority we can clearly indicate which use cases are operational an 
-      hich are not.</p>
+      <p>
+        If a use case document is correcly marked up with <code>fixme</code>
+        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.
+      </p>
+
+      <p>
+        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 <code>fixme</code> is given a
+        priority we can clearly indicate which use cases are operational an hich
+        are not.
+      </p>
     </description>
-    
     <steps>
       <step>
         <title>Make HTTP request</title>
@@ -341,30 +387,42 @@
         </description>
         <result>
           <p>
-            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.
           </p>
         </result>
-
-        <fixme priority="Blocker">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.</fixme>
-        
+        <fixme priority="Blocker">
+          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.
+        </fixme>
         <alternatives>
-          <p>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).</p>
+          <p>
+            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).
+          </p>
         </alternatives>
-
         <implementation>
           <description>
-            <p>The source document for use cases is, by default, called <code>useCases.xml</code> and is
-            located in the root of the projects xdocs directory.</p>
-
-            <p>The URL space <code>docs/**/useCases.xml</code> 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,</p>
+            <p>
+              The source document for use cases is, by default, called
+              <code>useCases.xml</code> and is located in the root of the
+              projects xdocs directory.
+            </p>
+
+            <p>
+              The URL space <code>docs/**/useCases.xml</code> 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,
+            </p>
           </description>
         </implementation>
       </step>



Mime
View raw message