Software Engineering Standards - IEEE SRS SDD

[Paolo F Cantoni]

whatshisnames

Ivar Jacobson?

Paolo

[jeshaw2]

A very interesting thread so far, but I would caution against the Systems Approach thinking (aka. the "water Fall" ontology).  If Design has a start, both an end and a sequential ordering of processes could be implied.  

Known generically as the Scientific Methodology (aka. RUP), parallel iterations are today's "Best Practice".  In that ontology, Requirements Gathering, System Design, Software Development, etc. are all timeless, parallel processes.  They began with the Big Bang and will end with the Big Collapse (I think  :-/).  Kinda like my wife's never ending shopping trip. Process boundaries are fuzzy, not crisp as in the Water Fall approach.

Project beginings, endings and internal milestones are management artifacts imposed on a system's process for defining points of review and approval. Process boundaries are management vehicles for assigning areas of accountability, and perhaos, modus operandi. For clarity of thinking, I like to keep the Whos and the Whens apart from the Whats, the Whys, and the Hows.

Just my descending $0.02 US

Jim

[HydraKeven]

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.
  

[Paolo F Cantoni]

Keven,

from the foregoing, I got to thinking...  (Dangerous, I know!)

If we viewed traditional "Requirements" as declarative requirements and Use Cases as a form of procedural requirements - would that provide a conjunction of view?

Personally, I think I could live with that.  It would also imply that if one wanted to list ALL the requirements in a model, one would get both...

It's like the responsibilities/requirements argument...  I a well formed system "If I can do something, I must be able to do it" - but we don't always have a well formed system (at least not initially)!  The Engineering/Science/Art is about resolving the competing factors.

Anyhow, just a thought for others to ponder and provide feedback on...

Paolo

[Paolo F Cantoni]

Hi again Keven,

What's your view on the role of the "Feature" element in EA in all this?  We have to do EN50128 design reviews and we use the "Feature" element to describe at a high (aggregated) level what the subsystem can do...

I guess sort of like an aggregated set of responsibilities.

TIA,
Paolo

[sargasso]

[As a tester]
Well y'all, ya know, its all very good and well to have a reel good set of bloo-prints to build this here chookshed.  But ya know what I reckon? I aint seen one blooprint set yet that matches the construction, 'cept for the set used by the builder himself and covered in pencil, crayon, mud and chickensh*t.
[/As a tester]

Now, therein lies the crutch of the problem.  

Between the dream (SRS) and the reality (the software delivered) lies a devil ... time.  And over time, things change.  Things like priorities, costs, estimates, budgets the weather, the government, decisions on what "I" really meant as "that requirement" and all those things that were "givens" at the start of the project ... like the delivery platform for instance.  (Ed: tautology?)  Maybe even things like "consistency" change, who knows?

[As a test manager]
Dramatis personnae
Pete (an esquire, commanding a view of his quarter acre)
Pam (Pete's significant other)  
Bob (a builder)

Act I, Scene I : Pete's Kitchen, one Saturdee arvo
(FX) Dialtone, digital dialing then ringtone (off)
Pete: Aw, g'day Bob, I wan'cha to build me a chook shed
Bob (O/S): Yeah? No probs, Pete.  How big?
Pete: Ooh, about 16 foot by twelve foot.
Bob: Yeah OK, I'll come round tomorra about lunchtime and give ya a quote.
Pete: OK mate, see ya then.
Bob: OK
FX: (Quick fade)

Act I, Scene II : Pete's backyard, "tomorow".
Bob: So, where do ya want the shed Pete?
Pete: Over here, near the back door.
Bob: Yeah OK. By the way, how many chooks ya got?
Pete: 'bout a dozen, I s'pose.
Bob: Well, I suppose we'll have to get Council permission then.  But that shouldn't be too much of a problem. I mean, there's no construction diffo's.  By the way, what's that  they're building next door?
Pete: Aarr, dunno. I think he's a vet or sumthing.
Bob: Yarr OK, anyway I'll get young Bob to knock up a cupla drawin's to go to tha Council. Should only take 'im a cuppla days or so.  I reckon we can knock this off for, say, eight or nine hundred bucks or so.
Pete: Ar, you beaudy! That's what I reckoned, too.  Let me know when you can start.
FX: Fade out with upbeat theme.


Act II, Scene I (some weeks later) : Pete's kitchen
FX: (O/S theme suggesting distant storm clouds, fade in to ..)
Pam: (Drumming fingernails on formica bench top) You! Just what exactly, are you doing.  What and why the hell are we spending money on Bob the builder!  Our kid's need braces, I'm still driving that bomb, and the neighbours are complaining about Bob's kid continually parking his ute on their lawn, what is he doing here anyway.
Pete: He's just measuring up the block for the chookshed.
Pam: The chookshed, the damn chook shed, all I asked you was to get off your damn arse away from the footy and go to the supermarket and get a dozen eggs for the kid's lunches.  What ever possessed you to decide we needed a chookshed.  Jeesurs can't you just for once understand that we are trying to run a family here!
FX: Phone rings
Pete: Got it, yeah hello.
Bob: (O/S)  G'day Pete. We got a little problem with th' shed.  It looks like we gotta put in extra drainage to satisfy the Council.  And it looks like we oughta move it away from the kitchen an' over in front of the pool.  But I reckon that we should be sweet if we don't strike any other problems.
...
By the way mate, I'm gonna have t' get a bit of a pump from ya on this project, can ya give us a advance of a cuppla grand? There's a lot of people I need to keep onside to get this one through?

Act II, Scene II (in the front yard, outside Pete's house. (In the driveway as a matter of fact))
Pam: C'mon kids get ina car!
FX: Mobile phone ringing, dog barking, 12225db plane landing  overhead
Pete: (into phone) Yeah what?
Bob: G'day mate, listen.
Bob: I reckon we gona have to do something about those foxes.
Pete: What "cloudy" foxes?
Bob: Well, ya know that there's been a ...
FX: 6.23^10db jet engine sound
Bob: ... so I reckon we're going to ha' to reee-assess the basic safety precautions ...
FX: several dozen Challenger launches combined with the dog biting child number three.
Bob: so, you OK with that?
Pete: OK with what? Oh sh*t I forgot to get that "Section 3" you needed, .. never mind, I'll call you tomorrow.  By the way, we're still going with your $800 price aren't we?
FX: Something like Krakatoa exploding, Mercury's orbit intersecting our's or at least a small supernova.
Bob: ... so you OK with that too?
Pete: Listen, I'll have to call you in the morning. Don't do anything until then, OK?
FX: Sound of dead phone connection ()

Act III, Scene I (many weeks later)
FX: (O/S theme suggesting an evil or at least very bad news, say a courtroom as the judge dons the black kerchief)  

.... some may call me a cynic :-)


Act III, Scene MCLXIII
FX: Fade in to reprise of original kitchen scene with Dialtone, digital dialing then ringtone (off)
Pete: Aw, g'day Bob, I wan'cha to build me a chook shed
Bob (O/S): Yeah? No probs, Pete.  How big?
Pete: Ooh, about 16 foot by twelve foot.
Bob: Yeah, no problems mate. I'll get our young Julia to drop round tomorra about lunchtme and get the paperwork started, I reckon we'll have it done come Michealmas. By the way, 'ow much d'ya reckon ya can pay for this project.

FX: Fade ... to black, ... or white, ... or just another day.

merry Hanukah
bruce

p.s. I may revise this.

Revision the first: Yes I know it's obtuse
Revision the second: Act II Scene II

[«Midnight»]

...
Revision the first: Yes I know it's obtuse

[As a Reader]
I was with you up to this point bruce, but I'm willing to look again

So where's this obtuse bit?
[/As a Reader]

[sargasso]

'probly just the cycle bit ?
"like a circle in a circle,
like a spiral in a wheel"

or, like whatever...


bruce

[HydraKeven]

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 )

[jeshaw2]

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?).

It is said that when something is measured, it is changed.  As a corollary, when something is analyzed, it is changed.
 
In systems development, we must not only capture and manage change, we must desire and embrace change wherever we can instigate it.  

Life is change; without it, there is no life.  Are we not all change masters?

-Jim

[thomaskilian]

To take it one step further: What is the true requirement? The one that I write down after talking to the stakeholder, or the one that he/she was actually thinking of? You all know it. No matter what I have written: in the end we start disputing about the meaning - the real truth. So life is not only change. It is also a permanent compromise.

[sargasso]

Mega culpa! OK OK mea culpa.

I was just trying to illustrate the type of problem we see at the "end" of the project [as a tester].  It has been patently  obvious to many that, over the life of a   p r o j e c t  , that "thangs quite oftend and ginrally" (sic) change.  Some of these things are well understood in the SE world, things like budgets and constraints, and frequently even the "P" word, policy.  

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

   getting better value to the "user-floor"

Some ten years ago I read "whatisnames" ⁽¹⁾ treatise on usecases and the more and more that I get up in the morning and head off once more to do "battle" with the same old lack of communication between the "receivers" and the "providers" of IT systems, the more I believe and see what he was trying to say:

"I just want to make a phone call"  
"What's a phone call"
"I just want to talk to Grandma"
"So, you want us to build a device, that will, given the incumbent Government develops the necessary infrastructure, legislates and empowers the defined demographic to intitiate and maintain (until such times as the medium is disconnected by either party, such parties including the initiator, the recipient and the infrastructure provider) a mechanism for the transmission of vocal communication between two parties ...

...bugger that, bugger the wolves, I'll just walk through the deep dark woods.

yours, in the hope that in 2008 we can talk with the "customers" better (or at least better - like )
bruce




(1) Shaddup Paolo, I DO know what his name is

[«Midnight»]

...

"I just want to make a phone call"  
"What's a phone call"
"I just want to talk to Grandma"
"So, you want us to build a device, that will, given the incumbent Government develops the necessary infrastructure, legislates and empowers the defined demographic to intitiate and maintain (until such times as the medium is disconnected by either party, such parties including the initiator, the recipient and the infrastructure provider) a mechanism for the transmission of vocal communication between two parties ...

...bugger that, bugger the wolves, I'll just walk through the deep dark woods.

...

Of course, today's enlightened answer might be:

"Oh, now I see. You need a map!"

Likely followed by:

"We don't do that here, but there's someone who does."
"No, I don't know the address, but I can tell you how to get there. Starting from Grandma's house, you go..."

I agree with bruce et al. But please remember that a good use case is not enough. Context too is important.

Just adding my 0.02 CAD, rapidly eroding in value.

David

[HydraKeven]

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

[Paolo F Cantoni]

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.

Experience, of course, shows that the "bleeding obvious" - isn't...

What's more we don't challenge that we actually do have a common undersanding...



Paolo