Show Posts

This section allows you to view all posts made by this member. Note that you can only see posts made in areas you currently have access to.

Topics - HydraKeven

Pages: [1]
Suggestions and Requests / 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.

Pages: [1]