SRS

Scope

The System Requirements Specification covers all use cases and formal requirements of the software to develop. The goal is to store all requirements into a specified data scheme, separated from layout and presentation views covered under version control.

Sources

Overview

The formal use cases are based upon the book "Writing Effective Use Cases" by Alistair Cockburn.

files and structure

The formal information will be provided as XML files. Additionally you can provide also a company logo and presentation customizations. Normally you have files as follows

use case root file (XML) use case files (XML) company logo (SVG)

sample document

Included into the fawkez project you will find a sample SRS document placed in the locations

src/doc/usecase
src/doc/req

The files are:

src/doc/usecase/sample.xml                            root file for formal use cases
src/doc/usecase/usergoal/consumer_registration.xml    sample file covering most recent features.

src/doc/req/hlf_summary.xml                           root file for high level requirements
src/doc/req/summary.xml                               root file for normal requirements
src/doc/req/DUM-1.xml                                 sample requirement file (RSS)
config/build-doc.xml                                  ant build file to include containing usecase 

target

Sample Root document

The root file contains information for the whole System Specification Document. it is also a "collector" for all formal use case files.

<pre>
  <?xml version="1.0"?>

  <!DOCTYPE usecases [
    <!ENTITY source "$Source: /cvs/root/legacy_opco/csp/implementation/csp-commons/dev/src/doc/usecase/sample.xml,v $">

    <!ENTITY summary SYSTEM "summary/summary.xml">
    <!ENTITY consumer_registration SYSTEM "usergoal/consumer_registration.xml">
  ]>

  <usecases>
    <info project="Sample" version="0.1"/>
    <bookinfo>
      <!-- injected into the docbook bookinfo element -->
      <authorgroup>
        <author><firstname>Dino</firstname><surname>Coppola</surname></author>
      </authorgroup>
    </bookinfo>
    <chapter>
      <title>Introduction</title>
      <para>
         The purpose of this document is to test xdoc
      </para>
    </chapter>

    &summary;
    &consumer_registration;
  </usecases>
</pre>

Build Instrcuctions

To build the sample SRS document, simply follow the instructions to checkout and build the FawkeZ project. Afterwards build the SRS document with

ant -Dxep.home=/your_xep_location/3.6.4 usecase

'''Unfortunately it is not possible to use Apache FOP 0.20.5 at the moment to build the document, due to some FOP bugs. RenderX will help us here.'''

Then you will find the produced documentation at build/usecases

Tag Description Formal Use Case

As mentioned already the tags in the formal, xml-based use case description are based upon "Writing Effective Use Cases" with extensions. For formal explanation of some of the terms used see (http://en.wikipedia.org/wiki/Use_case).

<version>$Revision: 1.5 $</version>

Should be managed by keywords of the Version Management System

<name>Consumer Registration</name>

Name of the Use Case

<goal>Consumer has been registered to the m-Wallet.</goal>

Goal which the use case is designed for

<scope>m-Wallet</scope>

Common scope covering several use cases, some kind of "package" name.

<trigger></trigger>

For example time based, event based, ad-hoc

<priority>high - phase 1</priority>

priority of this use case

<response_time>immediately</response_time>

Will the response to the actor be immediately, deferred,...

<frequency_of_use>ad-hoc</frequency_of_use>

Single shot, every 5 minute, ad-hoc

<actors>
  <primary>
     <name>Consumer</name>
     <channel>Web</channel>
  </primary>
  <secondary>
     <name>m-Wallet</name>
     <channel>Web</channel>
  </secondary>
</actors>

Actors with all channels they are using. There can be more than one secondary, and more than one channel per actor.

<stakeholder>Service Provider wants to get all relevant data of the consumer.</stakeholder>

Stakeholder and his motivation.

<precondition>System up and running</precondition>

In what condition the system, data and so on must be.

<guarantees>
  <success>Consumer is registered to the system. All relevant consumer data are stored.</success>
  <minimal>Consumer gets knowledge about the failure of the registration and the reason about it. </minimal>
</guarantees>   

After completing, interrupting the use case, what kind of guarantees must be fulfilled.

<success>
  <step id="1" desc="Display form">System sends initial formular asking for the MSISDN of the Consumer.</step>
  <step id="2" desc="Enter MSISDN">Consumer enters his MSISDN.</step>
     .
     .
     .
</success>

The steps of the use case in success path.

<extension id="E1" name="MSISDN_MALFORMED">
  <step id="1">System logs a warning.</step>
  <step id="2">System replies an error to the Consumer, that the MSISDN was malformed.</step>
  <step id="3">back to registration formular. <ref id="UC-10-1"/></step>
    .
    .
    .
</extension>

One or more extension path(es) to the success path. Could be alternatives, forks, errors, exceptions,...

<open_issue>Should there be mor information on this page?</open_issue>

One or more open issues relative to the use case.

<commitlog>
  $Log: consumer_registration.xml,v $
  Revision 1.2  2005/12/06 08:11:04  user
  Final Draft for consumer registration.

  Revision 1.1  2005/11/30 08:25:36  user
  initial draft of consumer registration added

</commitlog>

Managed by the Version Control System.

References

You could use in each tag references, which will point to other steps, use case succes, extension start points or formal requirements.

<ref id="UC-10-12"/>

This could be "DUM-1", "UC-4", "UC-3-2", "UC-6-E3-1", "UC-38-E2".

Html and Docbook

It is allowed in some tags like description and steps to use html odr docbook tags. They will be replaced by the appropriate tags/format of the goal document type (HTML, Docbook).