THE NLC SOFTWARE REQUIREMENTS METHODOLOGY
G.R. White, H. Shoaee, SLAC, Stanford, CA 94025, USA
Abstract help on both fronts. It separately outlines development
We describe the software requirements and and management methods, and is based on a
development methodology developed for the NLC combination of systematic structured methodologies
control system. Given the longevity of that project, and , in particular the Rational Unified Process, but
the likely geographical distribution of the collaborating incorporates elements from systemic methods .
engineers, the planned requirements management “Use Cases” (part of the Unified Modeling Language)
process is somewhat more formal than the norm in high are used to delineate user level requirements , but
energy physics projects. The short term goals of the also significant emphasis is given to the handling of
requirements process are to accurately estimate costs, non-functional requirements.
to decompose the problem, and to determine likely
technologies. The long term goal is to enable a smooth 2 METHODOLOGY FOR LARGE
transition from high level functional requirements to SYSTEM DEVELOPMENT
specific subsystem and component requirements for
Clearly defined documentation deliverables are
individual programmers, and to support distributed
itemized and described explicitly by the methodology.
development. The methodology covers both ends of
Table 1 summarises those deliverables produced for
that life cycle. It covers both the analytical and
each sub-system, application or component library;
documentary tools for software engineering, and
table 2 itemizes those for project management.
project management support. This paper introduces the
methodology, which is fully described in . Table 1: Development Effort Deliverables
1 BACKGROUND AND OUTLINE Vision Document Overall summary of purpose and
The estimated budget for NLC controls is about desired features
$0.5bnUS. The software development effort and Discussion Docs Textual discussion of Concepts
support infrastructure is about $75m, and represents Domain Model Use Case Model:
Diagrammatical and Textual
~475 person years of effort. However the funding
description of Use Cases (that is,
calendar requires that our staffing is not constant over scenarios of use from a functional
the development period. perspective).
Additionally, the software controls effort is likely to
be distributed and collaborative, involving EPICS Entity-Relationship diagrams.
developers and other participating institutions.
Therefore a formal methodology has been developed
Developers Guides Continuously updated programmers
which we hope will help to: 1) communicate future documentation as systems take shape.
intent and alternatives, 2) define the “treaty points” User Interface User interface mock-up
between sub-systems, and the interfaces between sub- Model
systems, and 3) help designers delineate how sub- Use Case Package Diagrams of relationships of packages
systems relate to the network architecture and data Report: and subsystems
infrastructure (such as data acquisition, control, Non-functional Textual description of system
requirements constraints and references
database and archiving). Document
The NLC controls project also has a very long Conflict Matrix How conflicting data acq or control
timeline and the objectives of our methodology change requirement will be handled.
significantly over time. In the short term our objective Taxonomy Summary of key functional attributes
is to effectively estimate the software and infrastructure Requirements RequisitePro db of requirements
requirements for the purposes of cost estimation and Matrices
project scheduling. In the long term our goal shifts to Cost Benefit Description of Cost, Effort and
Analysis functionality alternatives and
producing requirements suitable for producing accurate estimates
and clear designs. This methodology is designed to
Alternative Requirement Set
Figure 2: Com parison of Alternative Requirement S ets
Figure 1: Hierarchy of Requirements
The methodology distinguishes between functional application. Each requirement in a document is
requirements (which describe the desired behavior of captured using document parsing software. The
the system) and non-functional requirements (those resulting database of requirements can be queried,
concerned with the system’s effective implementation). visualized, and analyzed with the usual drill-down and
All requirements are viewed hierarchically; with very slice-and-dice paradigms .
general requirements such as the purpose and goals at Table 2: Global Deliverables
the top, followed by software features and then more Artifact Description
specific, possibly testable items and “system
requirements”. As such, each requirement may be CDR summary Summary of requirements work
traced from its antecedents to its consequents (see
WBS Work Breakdown Structure
Figure 1). Basic Design Statement of intent about the
Each requirement is assigned an explicit description Principles core architecture, infrastructure,
type, such as NEED, testable REQuirement, and so on and design of systems.
(though absolutely correct classification is not Sizing and Diagrams and text showing
necessary). For a very large distributed project, the role Performance nodes, data flow, and timing
and specificity of non-functional requirements is Specification requirement
System Boundary Summary of System Boundary
particularly pronounced because these typically define Analysis and Treaty Points
the interfaces and shared resources of sub-systems. Domain Analysis Document and Diagrams
Table 3 lists some examples of these very specific non- detailing domain objects and
functional requirements. their relationship
To each requirement are attached some “attributes” Enterprise db Schema Description of control system
(different attributes depending on the requirement type) entities and their relations
such as benefit, effort, cost, time, priority, risk of Glossary A dictionary of terms.
References Pointers to literature, both accl.
overrun etc, used for cost/benefit analysis. Physics and Engineering and
One important attribute is obviously the level of programming
“benefit” – captured as attribute values COULD,
Table 3: Non-functional Requirement Types Traced
SHOULD and MUST. Additionally though we predict
that in a large project there will be a large number of Abbrev. Description
alternative requirements for alternative solutions XREF Requirement of another system.
proposed, each impacting the requirements of
A description of a use of the system,
associated systems and changing their cost, time UC
described from an actors point of view.
estimates, and level-of-benefit. Therefore the
methodology proposes the documentation of An alternative NEED, or FEAT, and REQ
“alternative requirement sets” to manage the treaty set which can satisfy the purpose.
points between systems, their priority, cost alternative PERF Performance Requirement.
solutions, and to minimize friction and scope creep (see A database element, being a collection of
Figure 2). DBNAME attributes. This may describe a device, or
To manage all this formal documentation we use a some other aggregate.
requirements management tool from Rational Software TESTC A test suite, aimed at testing a Feature.
Corp. called RequisitePro, which is basically a database
The global requirements analysis includes the 3. IMPLEMENTATION AND RESULTS
construction of a “conflict matrix”, which attempts to
A formal systematic methodology was not used
define the needs of each control subsystem (RF,
before in the SLAC controls community, though we
feedback, beam monitor control etc) regarding their
had in the past applied the traditional approach very
priority in contention situations with other systems. In
effectively, and design reviews and code standards
the NLC this will be used define contention resolution
were enforced. Although we have not started the NLC
controls effort yet, we have adopted parts of this
The methodology includes a taxonomy for the key
methodology for the existing B-factory, and our effort
control system characteristics of each major subsystem,
to migrate the existing controls system to new
see Table 4.
technologies (i.e., off VMS). In particular the formal
Table 4: Controls Subsystem Taxonomy capture of requirements into a db, the use of distinct
Property Description vision, requirements, and discussion documents,
Initiation and How is the system started and forward references, iterative fixed period development,
Termination terminated. and continuously developed programmers
Duration For how long is the system typically documentation have all been implemented successfully
active and not idle and have increased productivity. We have also started
Frequency How often is it initiated. data sizing the NLC, and created the taxonomy of
Read/write Is the process mainly a reader or
subsystems. Some lessons have been learnt, and refined
Running State What machine state is this system for? our plans for the methodology, which have been
Shareable input Is the pulse related input data of this reflected in this paper. In particular, we had proposed a
system shared by other systems. very structured workflow, with identified roles for each
job function. That will probably be removed from the
Data handling and network performance methodology user guide, which is available in .
requirements are driven by data throughput and This paper has introduced the major concepts of the
processing requirements. In order to accurately predict methodology we developed. We would very much like
what those will be we constructed a “data sizing” to hear feedback on the methodology presented, and
taxonomy, including volume, frequency, latency, experiences of formal methodologies in use at other
resilience, structure etc, which helps to identify the accelerator software departments.
different data handling needs of each subsystem which
is involved with the same data. For instance, the data REFERENCES
handling need of a monitor display are very different to  Software Requirements and Analysis Methodology
those of the monitor data acquisition system, or the Recommendations for NLC Controls. G. R. White,
monitor data archive system. The result is a logical H. Shoaee. SLAC ESD Software. Available from
network and storage architecture. www-group.slac.stanford.edu/cdsoft/nlc_arch.html
We propose not to have monolithic design, followed  Rational Unified Process (RUP). Rational
by development phases, as in the traditional “waterfall” Software Corp. http://www.rational.com
approach. Rather we suggest an iterative, feature driven  Rational RequisitePro, Rational Software Corp.
approach, with fixed 6-week periods in which we http://www.rational.com
decide what features will be added or refined in each  Bertalanffy, Ludwig von, Brazziler, George.
period. More analysis and design of each feature will General System Theory, 1968
be done in early iterations of the overall project, more  Graham, Ian. Requirements Engineering and Rapid
programming and testing in later iterations. This is a Development, Addison-Wesley 1998
formalized version of “extreme programming” which  Liberty, Jesse. Object Oriented Analysis and
Design, , Wrox Press 1998
has recently become popular.
 Mumford, Enid. Designing Systems for Business
Over a long development period important design
Success, Manchester Business School, 1986.
ideas and other incidentals, which cannot be pursued in  Object Management Group (OMG) UML resource
the immediate term, are documented and tracked center, www.uml.org.
specifically as “forward references”.