forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgard...@apache.org
Subject svn commit: r405667 - in /forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo: ./ resources/stylesheets/ src/documentation/content/xdocs/
Date Wed, 10 May 2006 07:48:48 GMT
Author: rgardler
Date: Wed May 10 00:48:45 2006
New Revision: 405667

URL: http://svn.apache.org/viewcvs?rev=405667&view=rev
Log:
Use Case support, see http://localhost:8888/docs/developer/useCases.xml

Added:
    forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl
  (with props)
    forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml
  (with props)
Modified:
    forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap
    forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml
    forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml
    forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml
    forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml

Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap Wed May 10
00:48:45 2006
@@ -41,7 +41,6 @@
         <map:generate type="file" src="{lm:project.descriptor.{1}}" />
         <map:serialize type="xml-document"/>
       </map:match>
-      
     
       <map:match type="regexp" pattern="^(.*?)([^/]*)changes.xml$">
         <map:generate type="file" src="{lm:project.status}" />
@@ -107,6 +106,29 @@
         <map:serialize type="xml-document"/>
       </map:match>
       
+      <!-- =============================================================== -->
+      <!-- Use Case Pipelines                                              -->
+      <!-- =============================================================== -->
+      
+      <map:match pattern="docs/**/useCases.source.xml">
+        <map:generate type="file" src="{lm:project.useCases}" />
+        <map:serialize type="xml"/>
+      </map:match>
+      
+      <map:match pattern="docs/user/useCases.xml">
+        <map:generate type="file" src="{lm:project.useCases}" />
+        <map:transform src="{lm:projectInfo.transform.useCase.document}">
+          <map:parameter name="includeImplementationNotes" value="false"/>
+        </map:transform>
+        <map:serialize type="xml-document"/>
+      </map:match>
+      
+      <map:match pattern="docs/developer/useCases.xml">
+        <map:generate type="file" src="{lm:project.useCases}" />
+        <map:transform src="{lm:projectInfo.transform.useCase.document}"/>
+        <map:serialize type="xml-document"/>
+      </map:match>
+      
       <!-- ================================================================ -->
       <!-- HTML indexes                                                     -->
       <!-- ================================================================ -->
@@ -163,8 +185,8 @@
       
       <!--
         Create a snippet for inclusion in site.xml that provides a link to
-        all known programming languages for projects specified in
-        locationmap-projects.xml file.
+        all known projects specified in
+        locationmap.xml file.
       -->
       <map:match pattern="projectDetails/descriptorIndex.xml">
         <map:generate type="file" src="{project:content}/locationmap.xml" />

Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml Wed
May 10 00:48:45 2006
@@ -35,7 +35,11 @@
   <locator>
     <match pattern="project.status">
       <location src="{project:status}" />
-    </match>    
+    </match>  
+    
+    <match pattern="project.useCases">
+      <location src="{project:content.xdocs}/useCases.xml" />
+    </match>   
     
     <match pattern="projectInfo.transform.*.*">
       <location src="resources/stylesheets/{1}-to-{2}.xsl"/>

Added: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl?rev=405667&view=auto
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl
(added)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl
Wed May 10 00:48:45 2006
@@ -0,0 +1,174 @@
+<?xml version="1.0"?>
+<!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+    
+    <xsl:param name="includeImplementationNotes">true</xsl:param>
+    <xsl:param name="includeStepsSummary">true</xsl:param>
+
+ <xsl:template match="/">
+  <xsl:apply-templates select="//useCases"/>
+ </xsl:template>
+
+ <xsl:template match="useCases">
+  <document>
+   <header>
+    <title>
+    <xsl:choose>
+     <xsl:when test="title">
+       <xsl:value-of select="title"/>
+     </xsl:when>
+     <xsl:otherwise>
+       <xsl:text>Use Cases</xsl:text>
+     </xsl:otherwise>
+    </xsl:choose>
+    </title>
+   </header>
+   <body>
+    <xsl:apply-templates select="useCase"/>
+   </body>
+  </document>
+ </xsl:template>
+
+ <xsl:template match="useCase">
+  <section>
+    <xsl:apply-templates/>
+  </section>
+ </xsl:template>
+ 
+ <xsl:template match="steps"> 
+ 
+   <xsl:if test="$includeStepsSummary='true'">  
+     <section>
+       <title>Summary</title>
+       <ol class="steps">
+         <xsl:apply-templates mode="stepIndex"/>
+       </ol>
+     </section>
+   </xsl:if>
+   <section>
+     <title>Details</title>
+     <table>
+       <tr>
+         <th>Step</th>
+         <th>Description</th>
+         <th>Result</th>
+         <th>Status</th>
+       </tr>
+       <xsl:apply-templates mode="userDocs"/>
+     </table>
+   </section>
+   
+   <xsl:if test="$includeImplementationNotes='true'">   
+     <section>
+       <title>Implementation Notes</title>
+       <table>
+         <tr>
+           <th>Step</th>
+           <th>Notes</th>
+         </tr>
+         <xsl:apply-templates mode="devDocs"/>
+       </table>
+     </section>
+   </xsl:if>
+ </xsl:template>
+ 
+ <xsl:template match="step" mode="stepIndex">
+   <li>
+     <strong><xsl:value-of select="title"/></strong>     
+     <xsl:if test="@required='false'">
+       <xsl:text> (Optional)</xsl:text>
+     </xsl:if>
+   </li>
+ </xsl:template>
+ 
+ <xsl:template match="step" mode="userDocs">
+   <tr>
+     <td>
+       <xsl:number format="1.1.1.1.1.1.1" count="step" level="single"/><xsl:text>.
</xsl:text><xsl:value-of select="title"/>
+       <xsl:if test="@required='false'">
+         <br/><xsl:text>(Optional)</xsl:text>
+       </xsl:if>
+     </td>
+     <td><xsl:apply-templates select="description"/></td> 
+     <td><xsl:apply-templates select="result"/></td>
+     <td>
+       <xsl:choose>
+         <xsl:when test="not(fixme)">Implemented</xsl:when>
+         <xsl:when test="fixme[@priority='Blocker']"><warning>Not Implemented</warning></xsl:when>
+         <xsl:otherwise>
+           Implemented with fixmes:-<br/>
+         </xsl:otherwise>
+       </xsl:choose>
+       <xsl:if test="fixme[@priority='Blocker']">
+         Blockers: <xsl:value-of select="count(fixme[@priority='Blocker'])"/> <br/>
+       </xsl:if>
+       <xsl:if test="fixme[@priority='High']">
+         High: <xsl:value-of select="count(fixme[@priority='High'])"/> <br/>
+       </xsl:if>
+       <xsl:if test="fixme[@priority='Low']">
+         Low: <xsl:value-of select="count(fixme[@priority='Low'])"/> <br/>
+       </xsl:if>
+       <xsl:if test="fixme[@priority='Enhancements']">
+         Enhancements: <xsl:value-of select="count(fixme[@priority='Enhancement'])"/>
<br/>
+       </xsl:if>
+     </td>
+   </tr>
+ </xsl:template>
+ 
+ <xsl:template match="step" mode="devDocs">
+   <tr>
+     <td><xsl:number format="1.1.1.1.1.1.1" count="step" level="single"/><xsl:text>.
</xsl:text><xsl:value-of select="title"/></td>
+     <td>
+       <xsl:apply-templates select="implementation/description"/><br/>
+       <xsl:apply-templates select="fixme[@priority='Blocker']"/>
+       <xsl:apply-templates select="fixme[@priority='High']"/>
+       <xsl:apply-templates select="fixme[@priority='Low']"/>
+       <xsl:apply-templates select="fixme[@priority='Enhancement']"/>
+     </td> 
+   </tr>
+ </xsl:template>
+ 
+ <xsl:template match="description">
+     <xsl:apply-templates/>
+ </xsl:template>
+ 
+ <xsl:template match="result">
+     <xsl:apply-templates/>
+ </xsl:template>  
+ 
+ <xsl:template match="implementation">
+     <xsl:apply-templates select="description"/>
+ </xsl:template>
+ 
+ <xsl:template match="fixme">
+   <fixme>
+     <xsl:attribute name="author"><xsl:value-of select="@priority"/></xsl:attribute>
+     <xsl:value-of select="."/>
+   </fixme>
+ </xsl:template>
+
+  <xsl:template match="@*|*|text()|processing-instruction()|comment()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|*|text()|processing-instruction()|comment()"/>
+    </xsl:copy>
+  </xsl:template>
+
+</xsl:stylesheet>

Propchange: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml
(original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml
Wed May 10 00:48:45 2006
@@ -103,6 +103,31 @@
       </section>
     </section>
     
+    
+    <section>
+      <title>Use Cases</title>
+      <p>Projects can manage a document describing various use cases for the
+      application. These use cases can then be used to generate useful developer
+      and user documentation, as well as helping to track the implementation
+      status of features.</p>
+      
+      <p>Some of the uses of this feature are:</p>
+
+      <ul>
+        <li>during design - what needs to be done</li>
+        <li>during development - what needs to be done/has been done</li>
+        <li>during use - user documentation of common activities</li>
+        <li>during maintenance - how something was implemented</li>
+      </ul>
+      
+      <p>To see some examples take a look at:</p>
+      
+      <ul>
+        <li><a href="docs/user/useCases.xml">User Docs</a> for the Use
Case features of this plugin</li>
+        <li><a href="docs/developer/useCases.xml">Developer Docs</a> for
the Use Case features of this plugin</li>
+      </ul>
+    </section>
+    
     <section>
       <title>Project Details</title>
       <p>Project details are generated from a project descriptor file.

Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml
(original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml
Wed May 10 00:48:45 2006
@@ -47,6 +47,16 @@
     <forrestPlugins label="Plugins Index" href="site:forrest/plugins" description="Index
of Forrest Plugins"/>
   </about>
   
+  <docs label="Documentation" href="docs/">
+    <user label="User" href="user/">
+      <useCases label="Use Cases" href="useCases.html"/>
+    </user>
+    <developer label="Developer" href="developer/">
+      <useCases label="Use Cases" href="useCases.html"/>
+      <!-- In development: <featureMatrix label="Feature Matrix" href="featureMatrix/useCases.html"/>
-->
+    </developer>
+  </docs>
+  
   <projects label="Projects" href="projectDetails/">
     <navIndexes label="Navigation Indexes">
       <xi:include href="cocoon://projectDetails/index.siteSnippet.xml"/>

Added: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml?rev=405667&view=auto
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml
(added)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml
Wed May 10 00:48:45 2006
@@ -0,0 +1,376 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2006 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<useCases>
+  <title>Uses Cases for 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="useCases.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>
+
+        <ul>
+          <li>Requirements Documentation</li>
+          <li>Developer Documentation</li>
+          <li>User Documentaiton</li>
+          <li>Functionality Matrices</li>
+          <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/xdocs/useCases.xml</code>
+        </description>
+        <result>You have either a blank use case document or an existing one ready
for editing.</result>
+
+        <fixme priority="High">Create a DTD for use case descriptions.</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>
+
+        </description>
+
+        <result>You have the container for your new use case.</result>
+        
+        <fixme priority="High">Allow use cases to be split over several files.</fixme>
+      </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
+        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>
+          <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
+              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>
+            </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 
+          application.</result>
+        </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>
+
+      <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> 
+      </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>
+      </section>
+    </description>
+
+    <steps>
+      <step>
+        <title>Make HTTP request</title>
+        <description>
+          <p>
+            Request
+            http://localhost:8888/docs/developer/useCases.xml
+          </p>
+        </description>
+        <result>
+          <p>
+            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>
+        
+        <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>
+        </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>
+          </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>
+
+      <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>
+      </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>
+      </section>
+    </description>
+
+    <steps>
+      <step>
+        <title>Make HTTP request</title>
+        <description>
+          <p>
+            Request
+            http://localhost:8888/docs/user/useCases.xml
+          </p>
+        </description>
+        <result>
+          <p>
+            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>
+        
+        <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>
+        </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>
+          </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>
+    </description>
+    
+    <steps>
+      <step>
+        <title>Make HTTP request</title>
+        <description>
+          <p>
+            Request
+            http://localhost:8888/docs/developer/featureMatrix/useCases.xml
+          </p>
+        </description>
+        <result>
+          <p>
+            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>
+        
+        <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>
+        </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>
+          </description>
+        </implementation>
+      </step>
+    </steps>
+  </useCase>
+</useCases>
+

Propchange: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml Wed May 10
00:48:45 2006
@@ -46,6 +46,12 @@
         displaying information about one or more projects.</p>
       </notes>
       <action type="add" context="code" dev="RDG" importance="high">
+        Add support for Use Case documentation. This can be used to generate various different
+        types of user an developer documentation, such as step by step user instructions,
or
+        developer implementation notes. See <a href = "http://localhost:8888/docs/developer/useCases.html">
+        http://localhost:8888/docs/developer/useCases.html</a> for more information.
+      </action>
+      <action type="add" context="code" dev="RDG" importance="high">
         Use locationmap for resolution of resources and files. Resources are exposed via
         {lm:projectInfo.*}
       </action>



Mime
View raw message