Messages

1

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: December 06, 2007, 11:19:12 am »

I suppose, all I'm trying to say is, for the sake of your own sanity, consider why documentation has failed this craft before.
 
To me it's not because it was not well structured.  Further, I have read through ALL of the last three pages looking (yet again) for "good ideas". Yet I am still not convinced that the "structured analysis" approach is feasible. Every day that work I see trade offs, concessions, bitter and sometimes "better" arguments about ....  

While we are straying quite confidently from the topic, I'll make the point that we are dealing with a double edged sword.  The reason that the industry adopted structured approaches was because of the utter failure of unstructured approaches.  Does any one remember the time before the UML and why all the competing methodologies came about?  And why the UML was formed between three competing, overlapping, popular methods.  And why structured documentation by various agencies was developed and refined?

While structured approaches have their problems, the alternative is quite unacceptable.  The challenge is using a structured approach effectively.  It needs to be flexible for the project's scale and purpose (and I believe, Bruce, this is the real problem).  In this respect, I do appreciate the anecdotal "projects" presented.

The people using it also need to be able to communicate effectively.  If you've been following the educational trends, the demand for better communication skills by industry and government has changed curricula across the world.  Also, consider the time it takes for a new employee to understand a project with and without structure.  What about accountability?  I could go on (and I have).  No, I don't believe abandoning the "structured approach" way of doing things is a viable solution.

So, if all you want to do is string two cans between your's and grandma's house, your structured approach should be scaled way down to fit the need, not the other way around.  If you want to use electric wiring and cell towers, it should scale up.  If you want to use existing tech, it might even scale down further:

Customer:  "I just want to make a phone call"
Requirement: "User must make a phone call."
Design: "Use existing phone to make phone call.  See existing phone documentation."
Implementation: "Educate user to pickup the phone and make phone calls."
Test: "Check that phone works as per phone documentation."

Parents do this with their children all the time.  Just because some of these things are obvious doesn't mean they are not done.  They are just not done in a formal manner.

Many people skip the idea of requirements because of the "obvious" nature many of them represent.  The mind tends to realize the requirement and dismiss it immediately as the (design) solution forms.  We are trained like this from infancy.  But, when we are dealing with particularly hairy problems, the solutions are not as obvious.  We think though what the problem's parts need.  By breaking down a problem, we get back to familiar territory, see the need (requirement) and form the solution (design).  Again, the "need -> solution" process is fairly instantaneous in our minds.  Why we get stuck on problems is due to the unclear nature of the needs for the problem.

Problem: How do I make an anti-gravity machine?
Need: An understanding of how the gravitational energy for the force is generated and can be manipulated.
Solution: Currently, none exists.
Why: We know that gravity (force) exists, but nothing about its energy's source (i.e. some hypotheses, nothing testable).

Hopefully, I successfully redirected back to structured requirements and design for SE (but not entirely back to IEEE SRS and SDD).

2

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: December 03, 2007, 06:03:51 pm »

Paolo -

On Reqs In General: Concerning the SRS, the requirements form a basic contract between developer and stakeholders.  The SRS is what the developer says the system will do and the stakeholders agree or disagree, modify, iterate.  It is a forum document in that respect.

On Use Cases: Yes, I would tend to agree.  We could debate over formal names and how we view them forever.  They can be viewed as protocols, for instance.  In any case, I maintain that they describe "reqs" first and foremost--what a system should/must/can do AND are a tool for exposing more detailed requirements.

On Features: I also view these as requirements in the same respect as Use Cases, but at a lower level--the SRS definition of "Use Case" is a more customer centric requirements and a "Feature" is a more developer centric requirement.  They provide the requirement details for a subsystem described in/by a Use Cases.  They include a Seq. Diag. and functional reqs.  Class reqs can be a sub-specification of this or separate.  So you should be able to see a clear path in terms of requirements (and their aggregation?): SomeHighLevelReq -> UI Concepts and UCs(more detail) -> Subsystems(more detail) -> Features(more detail) -> Seq Diags, Functional Reqs, Class[attribute, method, instance, event reqs](most detailed) [your organizational structure may vary].  The non-functional reqs may also be somewhere in there or may be overall system concerns or both.

Bruce -

Your humor, sarcastic or not, is very appreciated!  It highlights the sorry state of affairs for software development.  It also show how we are sometimes in a wacko, surreal, learn-as-we-go industry.  I state with a fair amount of certainty that errors in communication are our number one problem--"blooprints" or not.  You almost make one of my points: having an implementation based on an SRS and SDD--whether it exactly follows them or not--is far better than not having them at all.  They are documents for everyone involved to share points of discussion.  If used properly, they improve the process and the implementation.

That reminds me of the probe that crashed into Mars in 1999.  The documentation was properly written, but not properly used.  Other procedures were also not in place to catch the mistake.  So in the end, the time it would have taken to use the system properly would have cost them far less than the billions that were lost in the instant the probe was destroyed.

I agree that change over time is a major factor.  Using systems and procedure that capture and manage change should be a part of any project.  In fact, they should be the core of a project's risk management strategies (we all know about "risk management", don't we?).

All -

I know it's not a perfect "Walgreen's" world.  I understand that we don't generally start with information that lends itself to develop a well formed system, much less friendly stakeholders that know what they want or all the issues involved.  But, our job is to create a well formed system.  We may not know all the answers either, but we should at lease be asking questions and using good SE techniques to help capture, isolate, and solve the problems we face.  I want to use EA as a tool for those techniques.

And it should be scalable.  If all you need is a "chook shed", any failure might be acceptable and the level of SE needed may be minimal.  But if you need to build a skyscraper...well, we're talking about systems that NEED to be well managed.  Right? (everyone take their Prozac and nod )

3

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: November 28, 2007, 12:55:26 pm »

Thanks for everyones input so far.  The written word in this manner is often interpreted with tones not intended by the authors.  I struggle with myself to read these with only the most soft and gentle of tones.

Wow, this became far longer than I intended.

First, I'll go back and address some of Paolo's questions.

Paolo - you are an incessant name dropper
---------------
---Off Topic---
---------------
No, not Peirce's directly--but, yes, as far as grammars as logic constructs.  I assume you are referring to Sowa's work on Conceptual Graph Notation for the existential graphs of Charles Sanders Peirce (as opposed to the other Pierce, Peirce vs Pierce).  My interests lie in grammar notation--specifically inferring grammar from graph data to mine for structure and applying the grammar by parsing graph data for validation or intersection.  Applications relate to the ever elusive semantic web and web page restructure for alternative display devices among others.

Try the more recent works of Bartsch-Spörl; Rekers and Schurr; Zhang, Zhang, and Cao; Kong; Inokuchi, Washio, and Motoda; Kuramochi and Karypis; Yan and Han; Holder and Cook; Joyner

...edges themselves normally don't have any (different) semantics

Not at all.  It has been traditional to apply semantics only to nodes (or at least ignore the edge semantics).  However, a graph can be transformed in many ways.  As a simple graph, [N1]->[N2], let "->" specify a directed edge.  Then, let [N1]--[From]--[To]--[N2] specify an undirected equivalent (where "->", "From", and "To" all have domain context--some may argue [N1]--[To]--[From]--[N2]is also a proper transformation, depending on your reference).  Then, "->" encapsulates the "[From]--[To]" semantic relation.  Also, "From" and "To" could be set as node ports in extended graph notations.  Therefore, we are free to give "type" to nodes and edges to express semantics.   Try this: N1 + N2 = N3 becomes
 [N1]-+->[N3]
 [N2]-+--^
is also
 [N1]->

• ->[N3]
   [N2]--^
  is also
   ([N1]-+-[N2])-=-[N3] where () is "graph as node".
  "It is true...from a certain point of view.", Obi-Wan Kenobi
  
  

  do you always qualify the parent-child by the type?

  
  No, it depends entirely on context, as the rest of your comment suggests.  We are free to say [N1]->[N2] where "->" implies some context (like order) and the nodes do not (direction could be reversed without any loss).  If we say, [parent]--[child], then the nodes should carry some context to give the edge meaning.  I refer to hierarchical algorithms, such as BFS and DFS, where "parent" and "child" are commonly used to imply order of the hierarchy levels in the abstract.  Certainly, a [child]->[child] relationship could be a valid "parent-child" hierarchy if the context of order is, for example, age.
  
  In effect, we commonly impose a hierarchy on any graph to step through the nodes in either some existing edge related manner or one we construct for the context.
  -------------------
  ---End Off Topic---
  -------------------
  
  

  OK... I think we can agree to disagree on this.  I agree we need better typing of external requirements, but it will be interesting to watch how your vision pans out...

  
  To boil this down to a simple discussion, I just want some (or all) EA elements to act just like EA "requirement" elements within the context of a Requirements Model diagram.  Specifying a special single internal requirement seemed like an easy way to do that.  Doing so within the existing elements will reduce redundancy.  EA should go farther with more detailed elements to link requirements to class attributes, methods, instances, and events.
  
  

  so maybe we have been talking at cross-purposes

  
  I'm thinking maybe we have.  I'm thinking, if I can do something, then I must be able to do it.  Therefore, the same.  To differentiate, I specify within a requirement some essential level of concern, such as priority, frequency, type, etc.
  
  

  Yes, interesting viewpoint.  I was of the view that a use case specifies HOW an requirement was to be realized.  But I concede that there are aspects of your statement above that are worth exploring.  Perhaps others (bruce - over to you?), may have more to say.  As I said earlier, this is a chance for all of us to explore our understanding and perhaps enrich/change it...

  
  I'm glad you see some merit in my statement.  Thanks, Bruce, for your support also.
  
  Thomas -
  
  A lot has changed in the last 21 years and I also believe SE is still very under-estimated.
  
  To be quite honest--all aspects of what we do are part of an overall Design process.  Design begins at Inception.  Having said that, SE is an engineering process using engineering principles.  For a given project (or a set of projects), the engineering principles divide the project into separate processes.  For SE, one is the software requirements specification (encapsulated by the SRS).  Another is the software design (encapsulated by the SDD).  There are others as I've mentioned previously.  And, depending on your perspective, there may be still others.
  
  As far as the definition of design is concerned, within SE and the IEEE, it is the plan which is used to directly construct the thing which it defines.  For a user's end product, this is the domain of the SDD.  A design, like a set of blueprints, is used to implement some thing that is given to a user to use.
  
  Now the engineer knows that the design does not come from thin air, but that there was some need for that design.  That need is expressed, within SE and the IEEE, as requirements.  This is the domain of the SRS.  It drives the design of the end product that is given to the end user.
  
  As Jim indicates, these processes are not mutually exclusive and are generally done in parallel.  I never claimed they were or should be done in phases.  We create the boundaries for management purposes.  I am not saying that "requirement" must be complete before "design" begins.  I am saying the "design" should be constructed from the needs specified as "requirements".
  
  I put on my "requirements cap" when I'm collecting, specifying, and refining requirements.  I divide these requirements into customer and developer requirements (C-Reqs and D-Reqs) and they form a hierarchy.  I put on my "designer cap" when I'm collecting, specifying, and refining design elements lifted from those requirements.  The product design elements also form a hierarchy.
  
  Now, knowing that I have requirements, why would I design something that does not have a need?  Just to be completely random or irrational?  I will restate the definition for a design: it is a plan for constructing a thing for which there is some need.  We can twist this and say the SRS is a plan for constructing the SDD for which the end product needs in order to satisfy the end user needs.  In this respect, all project management is Design in a glorified, inclusive sense.  But this broad definition doesn't really help us get to an end product.  Therefore, I impose a limit for the definition of an thing's design to the SDD.
  
  So, first, I have a need for something.  Second, I create a design to fulfill the need for that something.  And third, I build something to fulfill the need from that design.  Whether you do this all in your head, or on paper, or in some software system, like EA, is entirely up to you.  Again, I am concerned with "Software Engineering Standards" via the IEEE SRS and SDD.
  
  These issues left academia awhile back when it became apparent that the traditional fly-by-the-seat-of-your-pants approach to designing software left the industry with so many failures.  I attribute the slow adoption of SE principles to a lack of education, understanding, and appreciation toward SE.  Many feel that it will "cost" them too much and don't understand the scalability of the SE process. [I am NOT pointing any fingers, so no flames!]
  
  Jim -
  
  

  I like to keep the Whos and the Whens apart from the Whats, the Whys, and the Hows.

  
  I generally agree and do so within the wider scope of development--project management plans, configuration management plans, vision and scope, quality assurance, etc (see previous post). The statement was made to specify a separation between what I've been attempting to define and the "requirements" process and the "design" process.  Even so, there are elements of Who, When, What, and Why within the context of req. spec., such as within event specifications.
  

4

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: November 27, 2007, 05:03:07 pm »

We must keep in mind that I'm presenting the concepts of "requirements specification" and "design" in terms of the IEEE specification for the SRS and SDD.

Writing requirements IS a design process for the analyst.  It presents what a system MUST do.  It give insight in to the systems design.  Designing a proper requirements specification for a system is essential to designing to the system.

As a matter of fact a UC specification is written as (first!) part of the system design. Right after the informal requirements are collected from the stakeholders. Writing the UCs correctly is definitely a design process to me. In that respect I think that it actually Realizes the informal requirements.

This is exactly were confusion creeps in with regards to the difference between "software requirements specification" and "software design".  Stakeholders can be involved directly in UC specification, so UCs can also be part of the "informal" requirements.  UC are (first!) written to clarify these informal stakeholder requirements in terms of what you envision as the system's interface with the user--they refine them and give you ideas about the design, but they are far from "being" the design.  You can surely claim that they "define" aspects of the grosser informal requirements.  But they are still just requirements.  In the context EA presents, a requirement to requirement link would be an "aggregation"--their choice.

The result is that UCs tell us what, when, where a system should do things, which are requirement specifications.  In general, they leave out how as that is a design specification.  You would say "this" system/subsystem/module/class/whatever fulfills "that" UC specification.  In the context EA presents, that would be a "realization"--their choice.

If you suddenly drop requirements specification at the "informal" requirements, then I would say that you are lacking a complete requirements road map to your design.

I view a Use Case as a protocol specification between actors and the system.

You can and should.  These "high level" protocol specifications are completely within the realm of requirement specifications.  But, they leave out many, if not all, of the design detail--how you go about implementing the protocol.

5

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: November 26, 2007, 06:46:43 pm »

As stated, it also suggests that a "requirement" could realize a "Use Case" as "implementation" is user defined.  All this does is support the idea of "user context" for the model.

But, I'm concerned with more practical matters within the context of standard practices for requirement specification as given by IEEE (the topic title).  So, while its OK for a Use Case to "realize" a requirement in "some" model (and EA support this), it doesn't mean that it should be done or is done in practice.

More importantly, I want to model Use Cases (and other element types) AS requirements (which EA does not support).  The purpose is to support requirement decomposition via some connector type.  Aggregation is the currently supported mean for requirement decomposition within EA (and seems proper for its "whole-part" definition).  Doing so would follow closely the IEEE context for the SRS (requirements specification).

I can make a model show this, but the underlying support is missing.  Within a requirements model diagram, the "part" elements are not truly modeled as external requirements for the "whole" element.

6

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: November 26, 2007, 04:00:33 pm »

No offense taken.  It is the purpose of the discussion to clarify.  As such, I never claimed this discussion was based on or was restricted to UML definitions or terminology.

By the way, I am a visual computing / graph grammar specialist.  There have been several attempts to model the UML as a visual language.  Every parsing process I know about for the UML is sketchy at best.  If the UML was a true, well defined language, we could dispense with "code generation" and execute UML models directly.  Work continues in this direction.

No, I am not new to the UML--I just happen to disagree that the UML is "correct".  It applies rigidity in its definition while rejecting rigidity in its use at the same time.  It supplies a definition, but allow the user the flexibility to interpret that definition for their own use.  As such, the UML does not define how a user should specify, construct, or define design.  It simple provides some basic tools to model them.  It is based on graph theory, but then bastardizes its terms to define itself.  It is fairly well defined in this respect.

As you say,

This is unfortunate as UML "steals" all these common terms and gives them its own twist.

As far as terminology and definitions I use are concerned, I make the following disclaimers for your benefit:
----------
1. For any graph you care to consider, whether called a hierarchy, lattice, tree, etc., when a single node is selected as a root node, any sufficiently satisfying spanning tree defines a parent-child relationship from root to leaves.  Therefore, I use the commonly accepted definition for parent-child, not the UMLs.

2. All edges in the UML are simply labeled edges that specify context.  I implied that "aggregations", "generalizations", and "nestings" are parent-child.  I should also state they are directed edges which limits and defines the parent-child relationships within a satisfying spanning tree.

3. You said

although UML uses the term Package, it doesn't use it in the same way as we would normally accept

I counter that UML uses the term "Package" precisely as user intends it to be used.  It is a generic container tool.  It is the user's responsibility to define its use within a project and is used pervasively by various UML tools in the code generation process for languages, such as Java, for specifying package constructs.

4. It is commonly accepted that, w.r.t parent-child relationships, a child may have one or more parents.  The selection of the parent-child edge within the spanning tree is arbitrary as long as it satisfies.  Therefore, at will, we may selected the satisfying edge for the tree.

5. For any "hierarchy", a comprehensive spanning tree can be constructed by arbitrarily adding a single root/parent node that connects all "superior" nodes as children.  This process applies to any graph.  I apply this to requirements modeling by declaring a "single root project / application / system" requirement node to which all other requirements aggregate.
----------

To address your issue on "Requirements Element", this issue is no more serious than the way in which a user defines the use of the tool.  When I say "contains", I am stating in the request, a desire for a single internal requirement to define the element w.r.t. requirements as a requirement element.  Categorically, I desire elements to be "requirement" only, "design" only, or both (in general, both).  A simple way to do that is to declare the generic element with a requirements definition (a requirements element "contains" a requirements definition, its properties, which IS the requirement).  This definition should be within the generic element--as its internal requirement properties.  I do NOT want an external definition as it is redundant (see below) and does not provide the typing mechanism I need to specify the SRS (I need UI Concept, Use Case, System, Feature, Class, Attribute, Method, Instance, Event, etc., types to properly section the document).

You say,

an EA "internal" requirement is best conceptualized as an an element's responsibility

You may choose to view internal requirements as an objects responsibilities.  I have no use for internal requirements defined in this manner.  If an element it "responsible" for something then it "realizes" one or more "requirements" and each can be defined as external without exception.  This leave the realm of requirements specification and enters design.  I am not concerned with relationships between requirements and design.  This is well established in EA.  I am only concerned with the proper relationships between requirements.

Here is an example problem: EA views Use Cases as "design" elements as, by default, it realizes (external) requirements.  I can manually specify aggregate relationships for UCs in a requirements model, but EA still does not view them as requirements (they do not show up as external requirement "parts" for its "whole", if you wish).  I have never seen anyone "design" a Use Case, so it should not "realize" anything.  I have seen a system "realize" a Use Case and a Use Case used to specify the "requirements" for other requirements that, in turn, specify "design" elements that are "realize" or implemented,  such as classes.  Therefore, strictly speaking, a Use Case element is a "requirements" element.  Systems, subsystems, modules, packages, classes, etc. are generally "design" elements.  They "fulfill", "realize", or "are responsible for fulfilling" a requirement such as is specified in Use Case, Feature, and Class requirements.

However, there is no such thing as a class "requirement" element within EA.  We can arbitrarily declare one, but it is no different than any other requirement.  And, as I need to define a class "design" element for it anyway, there is a one-to-one relationship (I declare its need once in the requirements and its fulfillment once in the design) --therefore, it is completely redundant.  If I could declare the class element as a "requirement" within the context of the requirements model diagram, I could use the same element in a class model diagram, reduce the redundancy, and self-satisfy its "requirement" definition with its "design" definition.

Enough for now.

7

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: November 26, 2007, 10:11:27 am »

I'll answer this and the wide question that it implies as well as provide a suggested enhancement.  I'm sooo verbose!

The aggregation is context sensitive.  In this respect, I'm concerned about requirements.  This is a parent-child relationship detailing the refinement of requirements.  You could use "generalize" or "nesting", but EA had already defaulted to "aggregation" for requirements.

While packages themselves can be viewed as an "aggregation" of elements for design, they are not necessarily immune from being a requirements specification as well.  "Package" in this sense means the requirements specification of an actual implementation package (like a Java package which hold class elements), as opposed to an EA project convenience package (like the requirements model package or the class model package which hold the model diagrams).  Therefore, the requirements aggregation tree should shown the refinement of requirements to/from these packages (when they apply). The links points to/from them to indicate the parent-child refinement of the requirements--not the design elements they contain--in a requirements model diagram.

The "Project Browser" shows the meronymy of elements for your project, but those whole-part relationships do not necessarily follow the requirement relationships.  IMO, the project structure should follow some model structure, but as the requirements and design models usually differ, this may not be possible or is exclusive to one of the models.

Another way to show the "package" would be to place all the requirements of the package in the model and use a boundary element to contain them as the package requirements.  The boundary would have the package name anyway.  A third way is to use a requirement diagram element (like a functional requirements diagram) that holds the child requirements.  This becomes a matter of style and how my resulting SRS sections will be generated for the report.

The requirements model diagram should then have an accurate depiction of the requirements for a requirements document--as an aggregation tree.  This model can be extended to include the "realization" links to the design elements for an SDD.  For the package case, this would be a self-edge or a link between the boundary or diagram and the package.  Of course, aggregation exists for design elements as well, but the context is different and its resulting tree may vary greatly from the requirements tree.

The point is to represent a logical parent-child relationship for the requirements while reducing the redundancy.  I shouldn't need to create a requirement element for each Use Case and Feature as they are requirement specifications.  I shouldn't need to create a separate requirement element for each package, class, etc., when I can consider them requirements specifications themselves when specified via a Sequence Diagram for a Feature.   In context, the future "design" element may serve to represent its "present" requirement specification.  An (single) "internal" requirement for the element then begins to make sense.  Other not-so-obvious functional and non-functional requirements that are needed are specifically detailed as requirement elements in the traditional EA-way-things-should-be-done.

NOTE: When I mention tree, this may not be a true tree, as child requirements may have more than one parent.  While this may be view as bad form, consider one or more Use Cases that specifies several Features, each of which may specify the use of a common class.  The SRS document simply needs to  reference its first use and extend it with any additional requirement specifications (other techniques may apply).

My suggested EA enhancement: allow any element to be considered a requirement element, particularly if the element contains an internal requirement (a single internal requirement could be marked as its self specifications), especially when it is used in a requirements diagram.  Then, all the child links could be viewed and set as external requirement links within each element (properties->require).  By specifying the external requirements within each element, a requirements diagram and matrix could be automagically generated.

8

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: November 21, 2007, 04:31:37 pm »

KP reports on another post:

UML
Re: Requirement->Use Case->Activity Diagram

The connectors offered by the quicklinker are not the only ones you can use, just a list of commonly used ones. If you want to create an aggregation between a requirement and a use case, you may: the aggregation connector is in the "Custom Relationships" toolbox which is opened automatically on opening a Requirements diagram.

This makes many of the the requirements arguments I've been making obsolete.  However, packages refuse to have aggregate connections attached to (from) other elements.  Something about "breaking" the UML.

The only remaining part is aggregating classes.  I found out that I can add odd elements to other elements (ctrl-m) even though the "add..." feature only lists diagrams and links for a Class element.  I was able to add Components to a Class element.  These Components are (artificially) Attributes, Methods, Instances, and Events, each of which contains generic Object elements I can call (artificially) those types and aggregate in the Requirements Model diagram.

This would complete an effective SRS as I can place requirements in each element and hopefully structure the SRS report properly.  But, it is admittedly a hack and a half.

9

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« 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.

10

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« 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.

11

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« on: November 16, 2007, 04:58:11 pm »

Hey Paolo,

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.

12

Suggestions and Requests / Re: Software Engineering Standards - IEEE SRS SDD

« 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:

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.

13

Suggestions and Requests / Re: The SRS

« 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.

14

Suggestions and Requests / The SDD

« 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.

15

Suggestions and Requests / The SRS

« 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.