Author Topic: Software Engineering Standards - IEEE SRS SDD  (Read 10626 times)

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text!  All my posts are personal text...
    • View Profile
Software Engineering Standards - IEEE SRS SDD
« on: November 15, 2007, 02:16:54 pm »
This is long but I hope it is not viewed as a rant.  I only wish to improve the process and software we all use.

I find the lack of discussion about Software Engineering Standards somewhat disturbing.  So in an effort to start specific interest in this area, I am starting this new subject.  Specifically, I am interested in the inclusion of some kind of modeling standard or template that can be used to structure EA in such a way that is follows something close to the IEEE SRS and SDD documentation standards.

To get some search items out of the way, I am listing some terms / acronyms here:

IEEE - Institute of Electrical and Electronics Engineers
SE - Software Engineering
SWEBOK - Software Engineering Body of Knowledge
SRS - Software Requirements Specification
SDD - Software Design Document

To be sure, there are many other terms / acronyms to define, such as SCMP, SPMP, SQAP, STD, SVV, and "Vision and Scope".  I resist mentioning others as these are the core documents and others are generally detailed subsections of these.

What I would like to do is concentrate on issues related to the SRS and SDD--what I consider the "meat and potatoes" for software analysis and design.  Also, while the IEEE standard does not specifically detail Object Oriented (OO) use for these documents, I will admittedly direct this discussion toward OO usage as it is the common practice.  My main concern is that we need documentation driven models that use visual representations for clarification, not visual models that hide documentation details as a secondary process.

Another area of concern I will add (just to stir the pot a little more) is "Peer Review".

While providing a tool for specifying UML diagrams, I find that these pictures are just one small part of effective software analysis and design.  My opinion is that the UML is not much of a "language" at all as it lacks a well developed grammar to support its use.  In other words, it does not specifically support a parser on its so called "language".  There are attempts by researchers to do such a thing as well as creating graph transformation on these diagrams to represent the different "views" on a UML model.

However, my main concern is the realization of well established documentation principles on the diagrams developed and presented via EA.  The diagrams should support a documentation standard that a shop adopts and not the other way around.  EA is fairly flexible in its use and contains features to support the creation of documentation, but I find that it lacks needed structure in several ways:

1. It is based on principles targeting design, not requirements.  As an example, the SRS defines "Use Cases" (UCs) as a requirement capturing mechanism--they express design requirements, not design.  In general, they are SRS Section 2 elements--Customer Requirements (or C-Reqs, if you like).  Therefore, they fall squarely in the domain of requirements and specifically C-Reqs.  UCs are a stepwise documentation of user interaction with a system (I use "user" loosely).  The UC diagrams should support the documentation and could be generated "automagically" to create a kind of "table of contents" to the actual use cases. However, EA has adopted a reversal of this process.  A UC object is a diagram object that supports its documentation like a "red-headed stepchild", as if the documentation of its steps were an afterthought instead of its primary purpose.  I blame this entirely on a misunderstanding of the UML Use Case diagram.

2. The models defy the distinctions between requirements (via SRS) and design (via SDD).  The SRS captures requirements.  The SDD realizes or implements a solution to every SRS requirement in its design (ok, "every" might be a little strong, but that is the intent).  However, we need a refinement of C-reqs before we can realize the design.  The SRS Section 3 contains Developer Requirements (or D-Reqs, if you like).  Here is where we describe a (sub)system's "Features" in developer terms.  Each "Feature" is some refinement of a Section 2 item--in general, a refinement of a UC.  So, these features refine the requirements of Section 2 by specifying finer detailed requirements.  Here we support "Sequence Diagrams" as a "Feature" element in the documentation.  EA defaults Sequence Diagrams as a UC element.  This tends to blur the distinction of C-Reqs and D-Reqs of the SRS.  While requirements are specified in the Requirements Model, they are generally a raw list.  Their relations can be specified within the model, but they should automatically be related through the relationship between UC and Feature (a C-Req to D-Req relationship).  In addition, we introduce the concept of class objects within a Feature via the Sequence Diagram and its related reqs.  Therefore, we have a Class Requirements Model that resembles a Class Model.  However, it differs in that it specified requirements for the class, not its design.  EA has no notion of a Class Requirements Model.  The Class Model supports requirements in that it assumes <<realization>> of the requirements, but not the specification for refinement of Feature requirements.  A Class Model is a Design Model in EA that, if use to specify reqs, blurs the distinction between the SRS requirements and SDD design.

3. It lack fine granularity of requirements association with
the lowest level objects in a model.  By this, I mean I can attach requirements to a Class object, but not to its attributes or methods.  Ideally, methods need requirements specification as a refinement of class/feature requirements.  Obviously, attributes need requirements related to range at the very least.  In addition, their is no notion of an instance of a class in the Class object.  Instances of a Class are a requirement specification as shown in a Sequence Diagram.  Again, I stress these as requirements and NOT design.  These SRS requirements drive the SDD design process.  Effectively, these requirement specifications can "automagically" create (and link to) the majority of design elements needed by the SDD.

I have effectively described a relational description of requirements in terms of the SRS.  Section 2 C-Reqs (primarily UCs) are refined into Section 3 D-Reqs (primarily Features).  The Feature reqs are further refined into its Class reqs and/or Class Attribute and Method reqs.  As you probably have notice, I haven't even started discussion on Functional and Non-Functional reqs.

I will break up this discussion into several sub-topics as follows:

1. SRS
----------
The SRS concerns itself with requirements.  EA contains a Requirements Model, but I find that its use lack structure in several ways.  The SRS concerns itself with EVERYTHING that is "Requirements Model" related--the "what, why, when, where (but never how)" of software A&D.

2. SDD
----------
The SDD concerns itself with design.  EA is well developed to handle design with various UML based models.  But "pretty pictures" aside, the SDD concerns itself with EVERYTHING that is "Design Model" related--the "how" of software A&D.

3. Peer Review
----------
I submit a discussion on Peer Review purely as a means to highlight its importance to the process.  In effect, it is another noteworthy concept lacking in the discussion of software development.  Our shop has just recently adopted a peer review process using a commercial package.  In effect, I would like to discuss EA support for the use of these tools where EA can generate a documentation breakout (maybe by a directory structure based on the SRS and SDD sections / subsections with text files for each logical item.  These text files could then easily be added to a review systems as specific pieces as opposed to one large document.  This would help immensely in the debugging of the non-code related A&D documentation (BEFORE implementation) where it is most cost effective.

4. Other
----------
While I don't want to belittle the other documentation standards, I do not want to discuss them in much depth. I think there is enough on this plate to justify limiting the discussion to the SRS and SDD.

I follow this post with SRS and SDD related topics.
« Last Edit: November 15, 2007, 03:51:50 pm by HydraKeven »

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text! &nbsp;All my posts are personal text...
    • View Profile
The SRS
« Reply #1 on: November 15, 2007, 02:18:28 pm »
The SRS concerns itself with requirements.  EA contains a Requirements Model, but I find that its use lack structure in several ways.  The SRS concerns itself with EVERYTHING that is "Requirements Model" related--the "what, why, when, where (but never how)" of software A&D.

Our SRS is modeled somewhat thusly:

1. Introduction
1.1. Purpose
1.2. Document Conventions
1.2.1. Requirement Identification
1.2.2. Terms
1.3. Intended Audience and Reading Suggestions
1.4. Project Scope
1.5. References

2. Product Description
2.1. Product Perspective
2.1.1. Operations Concepts
2.1.2. User Interface Concepts
2.1.2.1. “Sample 1” User Interface Concepts
2.1.2.2. “Sample 2” User Interface Concepts (and so on)
2.1.3. Hardware Interfaces
2.1.4. Software Interfaces
2.1.5. Communications Interfaces
2.1.6. Memory Constraints
2.1.7. Operations
2.1.8. Site Adaptation Requirements
2.2. Actors and Characteristics
2.3. Product Features
2.3.1. Use Cases
2.3.1.1. Use Cases for <Some New Subsystem>
2.3.1.1.1. "UC-<Name>” Use Case
2.3.1.1.2. "UC-<Name>” Use Case (and so on)
2.3.1.2. Use Cases for <Some New Subsystem 2> (and so on)
2.4. Operating Environment Constraints
2.5. Design and Implementation Constraints
2.6. User Documentation
2.7. Assumptions and Dependencies
2.8. Apportioning of Requirements
2.8.1. Priorities

3. Specific Requirements
3.1. External Interface Requirements
3.1.1. User Interfaces
3.1.2. Hardware Interfaces
3.1.3. Software Interfaces
3.1.4. Communications Interfaces (Protocols)
3.2.System Requirements: Functional
3.2.1.Requirements of <Some Subsystem>
3.2.1.1.Features of <Some Subsystem>
3.2.1.1.1.System Feature 1
3.2.1.1.1.1. Sequence Diagram
3.2.1.1.1.2. Functional Requirements
3.2.1.1.1.2.1. REQ-1: Some Requirement (and so on)
3.2.1.1.2.System Feature 2 (and so on)
3.2.1.2.Classes of <Some Subsystem>
3.2.1.2.1.Class 1
3.2.1.2.1.1. Attributes of Class 1
3.2.1.2.1.1.1. Attribute 1
3.2.1.2.1.1.2. Attribute 2 (and so on)
3.2.1.2.1.2. Instances of Class 1
3.2.1.2.1.2.1. Instance 1
3.2.1.2.1.2.2. Instance 2 (and so on)
3.2.1.2.1.3. Methods of Class 1
3.2.1.2.1.3.1. Method 1
3.2.1.2.1.3.2. Method 2 (and so on)
3.2.1.2.1.4. Events for Class 1
3.2.1.2.1.4.1. Event 1
3.2.1.2.1.4.2. Event 2 (and so on)
3.2.1.2.2. Class 2 (and so on)
3.3. System Requirements: Nonfunctional
3.3.1. Performance Requirements
3.3.2. Design Constraints
3.3.3. Software Quality Attributes
3.3.3.1. Reliability
3.3.3.2. Availability
3.3.3.3. Security
3.3.3.4. Safety
3.3.3.5.Maintainability
3.4. Other Requirements

Appendices
Appendix A: Glossary (SRS)
Appendix B: Analysis Models (SRS)
Appendix C: Issues List (SRS)

Each Use Cases (2.3.1.1.X.) is modeled as follows:

Use Case ID: UC-<Name>
Use Case Desc:
Created By:               Date Created:
Updated By:               Date Updated:
Actors:
Description:
Scope:
Trigger:
Preconditions:
 1. <Some precondition>
Postconditions:
 1. <Some postcondition>
Normal Flow:
 UC-<Name>.0
   1. <Step 1>
   2. <Step 2> (and so on)
Alternate Flows:
 UC-<Name>.1
   X. <Step X, where X picks up at some step in the normal flow>.
    . <X can be described as substeps if needed, i.e., 5a., 5b.,
    .  etc., to maintain the normal flow steps>.
   [Optional Directive to resume at another (Norm/Alt) step or end]
 UC-<Name>.2 (and so on)
Exception Flows:
 UC-<Name>.X.E.1 (where X is the exception to Flow X)
   Y. <Step Y, where Y picks up at some step in flow X>.
    . <Y can be described as substeps if needed, i.e., 5a., 5b.,
    .  etc., to maintain the referenced flow steps>.
   [Optional Directive to resume at another (Norm/Alt/Exc) step or end]
 UC-<Name>.X'.E.2 (and so on)
Includes:
Priority:
Freq of Use:
Business Rules:
Special Reqs:
Assumptions:
Notes / Issues:

where:
Normal Flow is generally the base or "most used" flow.
Alternate Flows are other acceptably "non-error" flows.
Exception Flows are all the "error handling" exception to the other flows.

The definition between "alternate" and "exception" are understandably weak.
« Last Edit: November 15, 2007, 02:56:32 pm by HydraKeven »

Paolo F Cantoni

  • EA Guru
  • *****
  • Posts: 5875
  • Karma: +71/-77
  • Inconsistently correct systems DON'T EXIST!
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #2 on: November 15, 2007, 02:36:13 pm »
Hi Keven?,

This is an excellent idea.  I propose we use EA as a worked example - lets start developing the SRS for EA  8) 8)

We could set up stuff on the EA Wiki (see links elsewhere).

Somewhat, but not wholly, tongue in cheek!
Paolo
Inconsistently correct systems DON'T EXIST!
... Therefore, aim for consistency; in the expectation of achieving correctness....
-Semantica-
Helsinki Principle Rules!

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text! &nbsp;All my posts are personal text...
    • View Profile
The SDD
« Reply #3 on: November 15, 2007, 03:49:52 pm »
The SDD concerns itself with design.  EA is well developed to handle design with various UML based models.  But "pretty pictures" aside, the SDD concerns itself with EVERYTHING that is "Design Model" related--the "how" of software A&D.

Here is an example SDD:

1. Introduction
1.1. Purpose
1.2.  Scope
1.3.Intended Audience and Reading Suggestions
1.4. Document Conventions
1.4.1. Design Identification
1.4.2. Terms
1.5. Requirements Traceability Matrix
1.6. References

2. Architectural Design Considerations
2.1. Design Rationale and Constraints
2.1.1. Assumptions and Dependencies
2.1.1.1. Related Software
2.1.1.2. Related Hardware
2.1.1.3. Operating Systems
2.1.1.4. End-User Characteristicsa
2.1.1.5. Functionality
2.1.2. General Constraints
2.1.2.1. Hardware Environment
2.1.2.2. Software Environment
2.1.2.3. End-User Environment
2.1.2.4. Availability / Volatility of Resources
2.1.2.5. Standards Compliance
2.1.2.6. Interoperability Requirements
2.1.2.7. Interface / Protocol Requirements
2.1.2.8. Data Repository and Distribution Requirements
2.1.2.9. Security Requirements
2.1.2.10. Memory / Capacity Limitations
2.1.2.11. Performance Requirements
2.1.2.12. Network Communications
2.1.2.13. Verification and Validation Requirements
2.1.2.14. Quality Goals
2.1.2.15. Other Requirements
2.1.3. Goals and Guidelines
2.1.4. Development Methods

3. Architectural Strategies
3.1. Implementation Products
3.2. Software Reuse
3.3. Software Maintenance
3.4. User Interface Concerns
3.5. Hardware Interface Concerns
3.6. Software Interface Concerns
3.7. Fault Tolerance
3.8. Memory Management
3.9. Data Management
3.10. Distributed Computing
3.11. Control Issues
3.12. Concurrency
3.13. Communication
3.14. Other Management Concerns

4. Architectural Design
4.1. System Architecture
4.1.1. Top Level Component 1
4.1.2. Top Level Component 2 (and so on)
4.2. Subsystem Architecture
4.2.1. “Previous Component 1” Decomposition
4.2.1.1. Subcomponent 1
4.2.1.2. Subcomponent 2 (and so on)
4.2.2. “Previous Component 2” Decomposition (and so on)

5. Policies and Tactics
5.1. Implementation Products
5.2. Design Variations
5.3. Software Development Standards
5.4. Protocols
5.5. Algorithms and Design Patterns
5.6. Requirements Traceability
5.7. Quality Assurance
5.8. Maintenance
5.9. Interfaces
5.10. System Repository
5.11. Implementation Deliverables

6. Detailed System Design: Data Storage Components
6.1. “Subcomponent 1” Design
6.1.1. Detailed Design Elements
6.1.1.1. Classification
6.1.1.2. Definition
6.1.1.3. Responsibilities
6.1.1.4. Constraints
6.1.1.5. Composition
6.1.1.6. Uses / Interactions
6.1.1.7. Resources
6.1.1.8. Processing
6.1.1.9. Interface / Exports
6.1.2. Detailed Subsystem Design
6.1.2.1. Database Descriptions
6.1.2.1.1. Schema 1
6.1.2.1.1.1. Tables
6.1.2.1.1.1.1. Table 1
6.1.2.1.1.1.2. Table 2 (and so on)
6.1.2.1.1.2. Stored Procedures
6.1.2.1.1.2.1. Stored Procedure 1
6.1.2.1.1.2.2. Stored Procedure 2 (and so on)
6.1.2.1.2. Schema 2 (and so on)
6.2. “Subcomponent 2” Design (and so on)

7. Detailed System Design: Business Components
7.1. “Subcomponent 1” Design (an OO component)
7.1.1. Detailed Design Elements
7.1.1.1. Classification
7.1.1.2. Definition
7.1.1.3. Responsibilities
7.1.1.4. Constraints
7.1.1.5. Composition
7.1.1.6. Uses / Interaction
7.1.1.7. Resources
7.1.1.8. Processing
7.1.1.9. Interface / Exports
7.1.2. Detailed Subsystem Design
7.1.2.1. Inheritance
7.1.2.2. Attributes
7.1.2.3. Methods
7.1.2.3.1. Method 1()
7.1.2.3.1.1. Preconditions
7.1.2.3.1.2. Postconditions
7.1.2.3.1.3. Invariants
7.1.2.3.1.4. Returns
7.1.2.3.1.5. Process
7.1.2.3.1. Method 2() (and so on)
7.2. “Subcomponent 2” Design (an non-OO component: file format, function, etc.)
7.2.1. Detailed Design Elements
7.2.1.1. Classification
7.2.1.2. Definition
7.2.1.3. Responsibilities
7.2.1.4. Constraints
7.2.1.5. Composition
7.2.1.6. Uses / Interactions
7.2.1.7. Resources
7.2.1.8. Processing
7.2.1.9. Interface / Exports
7.2.2. Detailed Subsystem Design

8.User Interface Design
8.1.User Interface 1
8.1.1.Screen Images
8.1.1.1.Screen Image 1
8.1.1.2.Screen Image 2 (and so on)
8.1.2.Objects and Actions
8.1.2.1.Screen Image 1 Objects
8.1.2.1.1.Object 1
8.1.2.1.2.Object 2 (and so on)
8.1.2.2.Screen Image 2 (and so on)
8.1.2.2.1.Object 1
8.1.2.2.2.Object 2 (and so on)
8.1.3.Reports
8.1.3.1.Report 1
8.1.3.2.Report 2

9.Additional Material
9.1.Resource Estimates

Appendices
Appendix A: Glossary (SDD)
Appendix B: Design Models (SDD)
Appendix C: Issues List (SDD)


I've included a Section 6 separate from Section 7 to make a strong distinction between our Database needs and Class Implementation needs.  Section 6 is intentionally before Section 7 as 7 generally back-references 6.  This can be ignored as needed.

Section 4 is design in such a way as to allow Systems, Subsystems, Modules, Packages, etc. to be decomposed down to detailed design objects (Classes...wink, wink, nod, nod) where the actual detailed definitions are reserved for Section 6 and 7.  Detailed design objects in 6 and 7 back-reference Section 4.

Section 8 objects generally back-references Section 7 objects that they use unless these UI elements totally consist of Section 7 objects.  Then, Section 8 summarizes the Section 7 objects that form its UI element.  Yeah, it's a toss up.
« Last Edit: November 15, 2007, 03:50:26 pm by HydraKeven »

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text! &nbsp;All my posts are personal text...
    • View Profile
Re: The SRS
« Reply #4 on: November 15, 2007, 04:56:51 pm »
In effect, to simplify, I see the requirements process composed like so:

Requirements:

1. C-Requirements: Requirements the customer can understand
1.1 UI Concepts: Drawings and other related UI info
(subsection as needed)
1.2 Use Cases: High-level "User" to "System" requirements
1.2.2 Use Cases (including a High Level Use Case Diagram as a consequence of the following)
1.2.2.1 Use Cases for a System (including a Use Case Diagram as a consequence the following)
1.2.2.1.1 Use Case 1
1.2.2.1.2 Use Case 2
(repeat Use Case X as needed)
(repeat Use Case for a System as needed)

2. D-Requirements: Requirements the developer can understand
2.1 External Interface needs (new things, more detail for UI)
(Subsection as needed)
2.2 Systems: Functional Requirements
2.2.1 A System
2.2.1.1 Features of a System
2.2.1.1.1 Feature 1
2.2.1.1.1.1 Sequence Diagram
2.2.1.1.1.2 Functional Requirements
(repeat Feature X as needed)
2.2.1.2 Class Requirements of a System (a consequence of a Feature; a Class diagram could be useful driven by the Sequence Diagram)
2.2.1.2.1 Class 1
2.2.1.2.1.1 Attributes
2.2.1.2.1.2 Methods
2.2.1.2.1.1 Instances
(repeat Class X as needed)
(repeat A System as needed)
2.3 Systems: Non-Functional Requirements
(Subsection as needed)

I am divided on the issue of providing Non-Functional Reqs with the Functional Reqs in each System, Feature, and Class when they are specific to that area.  Separating them into a completely separate subsection seems to marginalize them.

thomaskilian

  • Guest
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #5 on: November 16, 2007, 10:23:42 am »
Thanks for that info :)

I think it would be nice to have a template EAP with that structure. I currently have a structure that fits my needs most times (based on CIM/PIM/PSM). However, sometimes I'd need something looking more like one of the structures you posted.

Paolo F Cantoni

  • EA Guru
  • *****
  • Posts: 5875
  • Karma: +71/-77
  • Inconsistently correct systems DON'T EXIST!
    • View Profile
Re: The SRS
« Reply #6 on: November 16, 2007, 03:19:41 pm »
Quote
I am divided on the issue of providing Non-Functional Reqs with the Functional Reqs in each System, Feature, and Class when they are specific to that area.  Separating them into a completely separate subsection seems to marginalize them.
Keven,

You could view the non-functional requirements as "Aspects" (see Aspect Oriented System Development - AOSD) that need to be "woven" into/between the functional requirements.

My AU$0.05
Paolo
Inconsistently correct systems DON'T EXIST!
... Therefore, aim for consistency; in the expectation of achieving correctness....
-Semantica-
Helsinki Principle Rules!

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text! &nbsp;All my posts are personal text...
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #7 on: November 16, 2007, 04:44:54 pm »
In the Requirements Management white paper, pg 13, I take exception to the following statement concerning relationships:
Quote
Realization
Requirements are implemented by model elements, such as use cases, classes, interfaces, components, etc. You may specify this relationship in EA using the realization link. A model element is marked as 'realizing' a requirement. Once this link exists, EA will display the requirement in the element responsibilities tab, in the requirement hierarchy view, and in the dependency and implementation reports, as well as the standard RTF output (See Requirements Documentation (Reports) below for more information on reports).

My argument is based on the IEEE SRS as it provides a well defined, yet flexible, engineering practice.  In it, as well as within other EA documentation, the Use Case definition is that they ARE requirement specifications.  Use Cases are a composite requirement refinement of a base requirement.  Follow this conversation with a customer:

"I want an application that..."
"It needs a screen that..."
"If I do <this>, the system should do <that>."

The application description provides my base requirement.  I can divide this into an aggregation of other requirements based on the customer discussions and further definition.  Now we get to the "screen" requirements.  These are effectively UI Concepts and they most certainly decompose into Use Cases, which are simply a description of a call and response between user and system.  In doing so, it defines requirements for how a system will interact with the user.  These, in turn, are refined into requirements for functions, classes and their attributes, methods, events, and instances.

My point is that all of these decompositions are aggregations of requirements and/or requirement objects, NOT realizations.  Use Cases are simply a mechanism to refine requirements.  They should be decomposed into Features, which are again a refinement of the Use Cases.

The SRS concerns itself solely with REQUIREMENTS and how they decompose along system/subsystem lines.  It drives the design.  The implementation objects, i.e. design objects, are a REALIZATION of these requirements and are in the domain of the SDD.  The SDD only references Use Cases to help a developer understand the purpose of the design elements.  Almost everything we do in Analysis is related to defining or refining requirements.  When done in a well defined manner, the design can be lifted directly from those requirements.  Therefore, the concept of "Requirement Driven Design".

As such, Use Cases DO NOT fall into the same category as Classes, Interfaces, Components, etc.  Maybe this is nitpicking, but as all us computer scientist know: syntax and semantics are important (even in the UML).

So lets get our terminology straight (w.r.t. well documented practices):
----------
Responsibility for a requirement is a "satifying" condition for the requirement.
Use Cases are responsible for nothing.
Use Cases are requirement definitions and help to refine requirements via their related Features.
Sequence Diagrams help to define the Features of a Use Case.
Functions and Classes, their Attributes, Methods, and Instances, "satisfy" or are "responsible for meeting the conditions of" requirements.
----------

Maybe others don't agree with this well defined concept of Requirements and its relationship to Analysis and Design.  However, as EA is a tool for these processes, it should support the development of templates that conform to these well defined practices.

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text! &nbsp;All my posts are personal text...
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #8 on: November 16, 2007, 04:58:11 pm »
Hey Paolo,

Quote
You could view the non-functional requirements as "Aspects" (see Aspect Oriented System Development - AOSD) that need to be "woven" into/between the functional requirements.


As it is, I do both.  I have a functional and non-functional requirements subsection listed under each Feature and element as needed.  I also have a general non-functional requirements area outside the features as well.  However, each non-func req is also categorical (reliability, availability, security, safety, maintainability, etc.) and this is generally difficult to manage as I get documentation bloat for every atomic element.  They are in effect aspects of the element, but are admittedly second class citizens in the traditional OO development process.

Trick

  • EA Novice
  • *
  • Posts: 5
  • Karma: +0/-0
  • I love YaBB 1G - SP1!
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #9 on: November 19, 2007, 05:20:01 am »
Hello,

Very interesting topic!
For I have been looking for a standard document to use with my diagrams.

I would like to add an information about SRS and SDD.
They're apparently also part of a US military standard called MIL-STD-498.
Along with SRS and SDD there are also other requirements documents like the SSS (System/Subsystem Specification).
The SSS is more general and is maybe better for C-Req.
I found those documents there :
http://www.pogner.demon.co.uk/mil_498/
The chapters are described, which make a little easier to understand what's behind the title...

Anyway, a SRS and SDD template would be most excellent!

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text! &nbsp;All my posts are personal text...
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #10 on: November 19, 2007, 11:48:39 am »
Trick brings up some an interesting point for those of you not completely aware of Software Engineering practices.  In fact there are a whole gamut of SE documents that help control the entire process.  In this discussion, I am focusing on the SRS and SDD, since the SRS as it focuses directly on requirements (which EA seems to want to support properly) and the SDD as it focuses on design.

These two documents, as well as the other, can be developed by an organization to provide a useful, orderly process to developing complex systems.  Here is an outline of the core documents:

Vision and Scope - Software Vision and Scope
SCMP - Software Configuration Management Plan
SPMP - Software Project Management Plan
SQAP - Software Quality Assurance Plan
SVVP - Software Verification and Validation Plan
SRS - Software Requirements Specification
SDD - Software Design Description
STD - Software Test Documentation

Other include the User's Manual and Maintenance Plan in this list.  Variations and other documents also exist.

All of these can be applied to the hardware side, or systems, as well.  Substitute "System" for "Software" if you like.

The "Vision and Scope" document is basically a project kickoff document.

The first 4 documents are project managements documents:
----------
The SCMP documents the management of all configuration items in the project, i.e., everything: personnel organization and responsibilities, policies and procedures, tracking project artifacts (tools, documents, code, etc.), schedules, resources, and maintenance.

The SPMP documents the management of the project's processes, such as an overview, deliverables, reference material, project organization (model, structure, boundaries, responsibilities, management process, technical process, and work packages (their content, dependencies, scheduling, resource requirements, and budget).

The SQAP documents the quality assurance objectives for the project.  It covers quality assurance management, tasks, responsibilities, documentation (referencing all the documents), standards, practices, conventions, metrics, reviews and audits (peer review process, reviewing other documents and processes), testing process, handling problems, securing tools, code, media, and suppliers, recording process, training, and risk management.

The SVVP document documents the verification and validation process.  It covers the V&V team, its members, their responsibilities, and process.
----------

The next 3 documents are the project development documents:
----------
The SRS covers all thing related to the projects requirements such as overview, C-requirements (project description, UI concepts, system interfaces, use cases, assumptions, constraints, dependencies, priorities), D-Requirements (a detailing of the C-reqs: detailed interface requirements, functional requirements as features including a sequence diagram, its specification of feature process requirements, and, if an OO process, detailing the specified class requirements (their attributes, methods, instances, and related events), non-functinal requirements including performance, design constraints, and quality attributes, and any other support materials.

The SDD covers all things related to the projects design.  It is driven directly from the SDD and includes an overview of the project, its architectural considerations(with reviewed alternatives), strategies, and design as a high-level design of the architecture dividing the project into its related systems, modules, packages, etc., and detailing their relationships, any policies and tactics for the design, a detailed design specifying all the processes, functions, files, formats, etc. at the lowest granular level (for an OO process, the classes with their attributes and methods including documentation and pseudo-code to direct the implementation process), and the UI detailed design.  Any additional supporting materials are also included.

The STD covers all thing related to the testing of the design and is driven by the SQAP, SRS, and SDD.  It includes documentation of the testing policy and procedures, test cases for the project including validation and verification of all project requirements present within the implementation, and design flaw documentation and remediation.
----------

The following standards can serve as a reference for most of the documentation presented in this discussion:

IEEE Std. 829-1998 IEEE Standard for Software Test Documentation

IEEE Std. 830-1998 IEEE Recommended Practice for Software Requirements Specifications

IEEE Std. 1008-1997 IEEE Standard for Software Unit Testing

IEEE Std. 1012-1998 IEEE Standard for Software Verification and Validation

IEEE Std. 1016-1998 IEEE Recommended Practice for Software Design Descriptions

IEEE Std 1058-1998 IEEE Standard for Software Project Management Plans

IEEE Std 1540-2001 IEEE Standard for Software Life Cycle Processes – Risk Management

IEEE 12207.2-1997 Industry Implementation of International Standard ISO/IEC 12207: 1995 (ISO/IEC 12207) Standard for Information Technology - Software Life Cycle Processes - Implementation Considerations

MIL-STD-498 Military Standard, Software Development and Documentation, US Department of Defense, 5 December, 1994

The Process Impact site is a good resource: http://www.processimpact.com/

Also, the book "Writing Effective Use Cases" is suggested.

KP

  • EA Administrator
  • EA Expert
  • *****
  • Posts: 2436
  • Karma: +29/-2
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #11 on: November 19, 2007, 09:15:18 pm »
Hi Keven,

Too many words! Can you precis please: What exactly are you suggesting or requesting?

My impression after speed-reading your posts is that you are requesting that your models be structured to a very specific format and ditto your output. Both of these things are under your control. You can incorporate Model Templates into MDG Technology files (here's the help page) and this allows you to distribute a standard model structure. Also RTF and HTML style templates can be distributed as reference data, allowing you to define a standard document format for your organization.

I hope this helps,

Neil
The Sparx Team
support@sparxsystems.com

«Midnight»

  • EA Guru
  • *****
  • Posts: 5651
  • Karma: +0/-0
  • That nice Mister Grey
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #12 on: November 20, 2007, 04:41:44 am »
Neil,

There are a couple of things that Kevin (or anyone) would need done to EA before this kind of thing would be truly possible. As an example, some kind of ability to filter items that are included in reports, based on properties beyond those allowed at present - along the lines of constraints filtered by pre, post, or invariant. I chose this example because it has been requested often, and for quite some time. It might be worth opening a dialog between Sparx and anyone about to take on such a project, so that these roadblocks can be resolved before too much work is invested.

The above said...

I think you're pretty close to the "how to" on this issue. While it would be nice to have this kind of standard setup in EA, it would also be nice to have a dozen or two other standards. But...

IMHO [read that again: IMHO] given the amount of effort involved, this kind of thing is best left to individual customers, or perhaps innovative add-on makers (i.e. let the market decide the value). If Sparx has this level of resources available for development, it would be far better to standardize and extend the core EA product.

David
No, you can't have it!

HydraKeven

  • EA User
  • **
  • Posts: 20
  • Karma: +0/-0
  • Personal Text! &nbsp;All my posts are personal text...
    • View Profile
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #13 on: November 20, 2007, 05:10:09 pm »
Neil,

Like the projects we do, this is not a simple topic.  The issues David is pointing out are valid.  The amount of text I use reflects the issues surrounding the problem.  As it is, an accurate SRS document cannot be modeled using the current system.

The main idea is that someone there needs to do some research on formal documentation methods so that EA can meet the greater needs of Software Engineering practices.  Just saying that EA can do this or that is not enough.

It seems like the documentation process has not been thought through and matched up well with well founded industry standards.  The filtering needs would go a long way to resolve this.

Also the way in which EA insists on connecting Requirements object with Use Case object as well as others seems problematic.  IMO, just about everything in the SRS is a "requirement specification".  This means Use Cases should be viewed as requirement specifications and connect to other requirements using aggregation connections within the requirements model.  Use Cases are an aggregation of Features.  Features specify Sequence Diagrams and are an aggregation of Functional and Non-Functional Requirements.  The Sequence Diagrams specify Class/Object/Method/Data Requirements.  Functional Requirements also specify Class Requirements.  Class Requirements are an aggregation of Attribute, Method, Event, and Instance Requirements.  However, EA insists that requirements connect to other model objects as realizations, which tends to break the aggregation (dependency) tree and confuse the idea of requirements specification with design implementation.

To implement this in EA, I need to create a Requirements aggregation (dependency) tree and link the "other" model elements using <<realizes>> connections in a one-to-one manner.  This seems completely redundant, unnecessary, and obtuse.  On this point, EA forces me to confuse the idea of requirements specification with design implementation.

If EA were able to capture the requirements within modeling objects and use a Requirements diagram to model the Requirements Aggregation tree through these element, we could simplify its representation, traceability, and documentation model.

I'm also lost on the whole idea of using "external" and "internal" requirements within model elements.  To me, "internal" requirements are next to useless as they can't be linked in the Requirements tree or referenced in any meaningful way.  It seems to serve as a temporary repository for a requirement until its proper location within a package/diagram is found (to become an external requirement anyway).

See and read "in depth" my other posts on this.  If you think I'm wrong on any of this, show me a detailed HowTo, tutorial, or other help documentation that will clarify these issues.

thomaskilian

  • Guest
Re: Software Engineering Standards - IEEE SRS SDD
« Reply #14 on: November 21, 2007, 02:45:31 am »
You're speaking "out of my heart" like we say in Germany. I fully agree with what you say and would like that Sparx could rework that requirements stuff accordingly. However, I fear that there's not much hope. We had been discussing that years ago but there was no real change up to now. Somehow I got used to EA's way and adopted it accordingly. The whole thing about capturing and modeling requirements is (my point of view) too complex to be handled with EA alone. During the capturing phase you would need different techniques (like Mind-Mapping) you would do in non-EA tools. Then you need something to really Manage your requirements (what happens if... what impact does it have... etc.) which you can't really do with EA. I'd like to see that EA could cover all aspects but I know that will never be the case. So I know what EA can do and I'm happy that it cover such a bandwith.

However, any improvement is very welcome.