Modeling Requirements with SysML

Editor's Notes

• #2: In this session you will learn how requirements modeling from Systems Engineering has been mixed with UML and how this can greatly ease the creation and tracking of requirements. Finally project requirements are no longer a big document that you use to prop your door open or keep handy in the winter for kindling. Requirements become living entities connected throughout your design and code.  Developers can see and show what they have done and not done. It is also simple to do cost and risk analysis without paying for costly tools. This is not tool specific, just a set of techniques that can be implemented with any modern UML tool.
• #4: I’ve already mentioned that people are a root of the problem. Let’s look at how they create that mess.
• #6: The problem however is that a clear set of understandable and testable requirements give you a lot of benefits.To be clear, bad requirements cause the reverse of the benefits.
• #7: I also want to quickly cover this subject in terms of Agile. If you don’t mention Agile or the other buzzword, SOA, nobody will come to your talk. But we do need to be clear about how Agile fits with both modeling and requirements.One of the great myths of Agile is that it does away with requirements. There may be a few crazies out there that go to that extreme, but that is not the wide view. It is also something that can’t simply be thrown away depending on the industry or corporate rules. What Agile does do is like many other methodologies, reduce requirements to those that are the most useful. Agile also tries to focus on functional and testable requirements but does not loose non-functional requirements and places special emphasis on performance.Agile is also different from many methodologies because it allow requirements to be living rather than static. If you have iterative development you need to change priorities of what requirements to support and we also know full well that ‘some’ requirements change during the lifetime of an application.SysML requirements fall into the Agile process rather cleanly. There are a few things you want to do to aid iterations like extending to add data for sorting and estimating, but it is rather simple to do. Modeling is still a bit of a sore subject with Agile folks. A key reason is that they spend vast sums of money on IBM tools and training per developer and call that a waste because you don’t get what the salesman said you were going to get. We believe firmly that tools matter in Agile, it is all a matter of how deep you go and the value you can get from your tools. The only thing I want to say is that it is how you use your tool and the value you get. If you don’t concentrate on your tool, you will get no value. We preach understanding and we try to pull as much value as we can. Requirements modeling is just one more way of doing this.Reference:Agile and Iterative Development: A Manager's Guide
• #8: This is another way to look at the Agile verses the Modeling fight.
• #10: Now we need to understand an implementation of requirements in UML. I am using the SysML profile which contains a requirements metamodel. Oddly it took system engineers to come up with this. For some reason software developers did not think this way. However it is wickedly obvious. When I first saw this I almost got a concussion from that “I could have had a V-8” slap to the head.The primary reason for their thinking this way is that in aerospace they still base everything on requirements. The people involved involved in creating the spec with big contracts with complex systems with many lives depending on their success. You are really careful when launching a rocket, flying a plane of people, or dropping a bomb.The creators were also hardware oriented. They think in terms of parts and systems made of parts. This is another reason why the idea works well as it relates well to the real world.
• #11: UPDM as an extension of UML is nothing more than semantic tagging (vocabulary) and rules about our grammar.From a dictionary you can write all the world books. With UPDM you can describe any enterprise.I don’t want you to think there is a mystery here. This isn’t ontology or the semantic web. This is similar, but simpler.With UML we also have visualization of the grammar. This is highly important, because we need to communicate.
• #12: The goal for SysML was to create a model of systems and have traceability to its requirements. The simplest way to meet this goal was to also model the requirements themselves. Once you start thinking this way, a lot of things become obvious.I was talking with one of our competitors a while back and he was saying proudly that they have been doing this for years. Problem is that they had not taken approach that truly separated the requirement from the object of the requirement. What this meant is that you could not reuse a requirement or do other things with it. The requirement was just part of the documentation for the class or interface. SysML requirements is far more flexible and creates more usable value through the lifecycle.The picture here is part of the story. Requirements have been around for a long time, like the castle. But like really old things, they fall down – sometimes they are torn down by their enemies. This castle in Lithuania was pretty much just foundation. It was rebuilt using enough modern technique and knowhow to bring it back to its former glory. Requirements in SysML are similarly rebuilt from very old foundations but with modern techniques.
• #13: The core idea for modeling requirements is not just the requirement. Yes, we need to do that right, but we also want to model everything else. This drawing is missing one thing. Requirements also are related to other requirements. We refine, derive, and group requirements based on other requiremetnsts
• #15: The modeling of requirements has a lot of value because of the rest of the model. We can show dependencies between the requirement and other things. Look at the advantages! The last, “one source of truth” is not really obvious but is very important. Even with user stories, use cases, tests, and other data, the requirement is the key storage for truth. I don’t mean to say truth is not in those other areas. For example a refinement via a use case should be reflected back at the requirement. The key is that we have a way to correct a requirement. But as you proceed you add more and more references to a requirement. In the end we have design, implementation, tests, and the analysis linked to the appropriate requirements. You can go anywhere and find what requirement the work is related to.The web of data helps understand the impact of change, find gaps, etc. Tools are important, but we are not talking rocket science. This is just simple UML modeling. Tool makers can make this easier, but nothing prevents you from applying this quite simply.
• #16: Here are the artifacts we use. Note that these are just related to requirement but not all you can use. As I have said before, we can link and reference many other artifacts.Note that copy is to re-use a requirement and trace is a general concept that
• #18: The one thing that gives all of this power is the use of dependencies. They give you a way to generically relate things in the modelIf I then use stereotypes like satisfy and verify, I create a contract dependency.I can also manage the dependencies and watch them come and go. So if a requirement goes away, all the code/tests loose the relationship and I can choose to take that stuff out of the code.
• #20: Let’s start with a few of some requirements that should be true all the time. These are not requirements that are directly associated with business requirements, but are true for most applications.The big problem with business requirements analysis is that we often forget the things that are always true. Usability and data integrity are two important groups of requirements that are almost always forgotten. These things are also easily tested and reuse can be very high if you assume these things are always true, you always address them.Login is my favorite example. There are a lot of requirements. The business requirements are usually minor, consisting mainly that there is a login. What usually happens? Nobody thinks of these requirements. Login across your products don’t behave the same. There is no re-use. New bugs are created for every implementation and the login isn’t right until version 3.5 service pack 2 of your product.I often try to log into web sites and find my password does not work. Why? I use strong passwords. More than 8 characters. But I got no warning, there were no errors, and even when I typed it twice and the system will not let me continue unless the passwords match. But the system truncated to 8 and did not tell me. A simple test would have found this, but not without a requirement that says what is good and what is bad and that I test the behavior of both.It may seem like a lot of work. The reality is that if I find a standard requirement, it is linked to both the older code and older tests from prior projects that I don’t have to think about.Re-use should happen because of a cascade from your requirements. To expect re-use because you have a library is hubris. You need a reason to re-use rather than just omponents that can be re-used.
• #21: Looking a little closer, you can see the relationship I am using is containment. One requirements contains finer requirements. You can use a derive, but I like this because it is easier to manage. I do use a derive that you will see in a moment, but usually only when I cross domains or concepts which lead to the need of a requirement.
• #22: Now I am looking at the application requirements (in blue). Note that I have a lot derived from my standard requirements. Not seeing the whole set of requirements because I want to show the different points of view. It is important to understand that each of these have different points of view and different tests to confirm or can control a generic test with application specific requirements. A good example is an error dialog. We can use a lot of standard requirements for look and feel, but the reason for the error message and the message itself is specific only to the application.
• #24: JSP http://en.wikipedia.org/wiki/Jackson_Structured_ProgrammingCRC http://en.wikipedia.org/wiki/Class-Responsibility-Collaboration_cardCooper InteractionDesign http://en.wikipedia.org/wiki/Interaction_design
• #25: Use cases are nice. But what do they show? Quite simply a use case should show users and action oriented interfaces. The Use Case is great for this, but it is not the whole story. It can help validate the user interface, but that is where at lease the stops.We can go deeper into the use case descriptions, the activity, and sequence diagrams to refine further. But this is refinement of the design in many cases, not ensuring that the design meets specific requirements. Requirements are different. Different level of abstraction. Different purpose. Different usage.
• #26: The important thing to notice here is the text. The use case does a very specific job to describe the use. The requirement is a different twist. The blue boxed requirement is a usability requirement. The pink box is a functional requirement. The two requirements are from different points of view. You might say, well, we met one requirement, why have two? Simply, the way we would like our requirements to work is that this is partially coincidence and the other that it is confirmation of good design. In this case, the designer could leave out “cancel” login and just force the user to “Close Application”, but this would reduce usability as our other requirement shows. To reinforce the principal applied, there is a reason for that usability requirement in that it should force into existence functional requirements. This does not always happen, but the point is that it is good. But…. Why the heck can I say this? Simply this diagram mixes the requirements and use case so that I can see this.
• #27: So, if are assuming that we can’t rely on people successfully implementing requirements, we need a way to test. The beauty of the Agile is the test first methodology. But there is a problem. Test first concentrates mostly on code. That is fine, but it does not usually test for requirements but implementation. Nothing wrong with that, but we need to cover both implementation and compliance to requirements.
• #28: One of the important uses of a requirement in a model is linking the test cases. This is just following what we just did with the use cases. We get the same power. We can do this with JUnit as well as other test frameworks.Now you might say, why not trace to the use case for testing? Sure you can do that, but remember that use cases are primarily for interfaces. There are a lot of requirements that don’t have anything to do with interfaces.Looking at the authenticate via LDAP and the cancel action requirements you can see how these are not easily applied to a use case. The LDAP requirement is an interface implementation and cancel action is a requirement that comes from our usability standards which are expressed in terms of requirements.
• #29: We have talked about our requirements. What about the specific GUI? We can do that too. In MagicDraw this is rather simple because I have a very special GUI diagram that uses UML to design a GUI.
• #30: Once we have the elements, we can then attach our requirements.Here we have the cancel button and default action buttons shown.
• #31: Just in case, why not trace the use cases too?
• #34: Time to link the requirements to the implementation. This is one of our more important diagrams because it shows where we actually do the specific work.The links are called Satisfy dependencies and are drawn from the implementation to the requirement they fulfill. We can link specifically between either a package, component, class, and interface, a method, or even a class variable if we want. This should be more than enough granularity to show how a requirement is satisfied. In addition to the requirements, note the yellow boxes. These show data about the linkage between the requirement and the implementation. We additional details about the priority and the hours associated with meeting the requirements.
• #36: You have already seen how we associated the hours and customer priority. We can add a lot of other data or calculate metrics that help us with project planning, management, and execution. Usually this is done with stereotypes applied or dependencies drawn between artifacts, or combinations.
• #38: If we can see what we are doing with links between design, test, implementation, and our requirements, imagine what we can not see. If nothing links to a requirement, it is a gap. If nothing links code to a requirement, perhaps it is not meeting any requirement. Any artifact in our design that is missing an association can be suspect for either too much work or not enough.
• #39: In these two matrixes, we use the tool to show us one type on one axis and our requirements on another. The upper left is showing Verify relationships and on the lower right, satisfy relationships. Some have links and some do not. You could create these charts with reporting or in our case a plugin that was written to do the job. The data is in the UML model and that is what is important.
• #40: Here is a chart showing how we refined requirements with our use cases. Note that some use cases have more than one requirement that they satisfy.
• #41: What we have just shown can follow a simple process. You could choose a different process, but the steps are going to be fairly simple. If you were story driven, you might start there, move to use cases, then requirements. Or if you were test driven, you could start there. The point is however that this technique can fit within many different methodologies and give significant value.The importance of the data can also aid many methodologies by adding more data for estimates and even success of your implementation. I have seen a lot of spreadsheets in my time and this beats that by quite a margin because we manage the data in the model.
• #42: For the developer, the specific iterations are also fairly simple. Because design, tests, and requirements can all be managed in the model, it is easier to do iterations and manage the reporting many managers want. The side benefit is that a lot of the data is just as important to the architect and developers. In our own company we are working on ways to integrate model data with task data in systems like Jira.
• #43: The problem with change is staying on the road. Sure we might want to change direction, but we don’t want to do this at the expense of chaos.
• #44: Why modeling and requirements?
• #45: So, you may still not like requirements or might think that though this is cool, what else can you do?
• #46: First, I want to add requirements knowledge as additional documentation. Simple idea.We don’t stop there. With good Java annotation we can inject the data for logging or even specific methods to trigger monitors to ensure that code related to use cases or requirements are actually executed during tests. One cool thing to imagine is that code can log that it should be called during specific unit tests. Imagine a login test that includes in the log that the code that was executed was related to a use case, the requirement, and a specific test case. The cool thin is that you get this for free.
• #47: Real quick, here is an extension in UML that I have used to generate code to support Java annotations.These annotations are to specifically support requirements traceability.
• #48: Here are the annotations used in the code.
• #50: So, that is what we have for today.Requirements is still hard. We can’t deny that. But if we change the way we create, trace and use requirements, we have more knowledge, make fewer mistakes, and have better feedback.Don’t look at this as just requirements. There are simple ideas here. UML is very malleable and there is a lot of room for very pragmatic things to help you improve and be more agile.
• #58: Quite simply the tale here is about setting goals which guide your path. There are an innumerable number of methods. The world seems re invent and then re-invent techniques to get us from point A to B by analysis, diagram, and or process. The simple fact of the matter is that people are people. Failure can come from the creation of requirements or the interpretation and implementation of requirements. The root of all all failure is the human. Murphy just brought this to our attention by pointing to the real root of the problem: People. Think about the overbuilding of systems and the backup systems in airplanes and spacecraft. Is this for the possible failures of the equipment? No. Think about how this comes about, a human designed it and we have issues of price, performance, weight, etc. These are human set criteria that contribute to the possibility to failure.Failure is inevitable. The key then is to reduce failure and to have methods that can recover from failures or limit their affect. For requirements we want to improve understandability. On consumption we need to improve our ability to execute and to verify we are meeting requirements. Someplace in the middle, we need to choose the right requirements. So, where do you want to go?The key then is to choose a method – or two or three – that define what you want and then use a technique that helps prove that you are getting what you want. The technique here will focus on everyday requirements that are modeled rather than just text. The tool is UML based and there are many tools like it. No Magic’s tool is better of course! We also believe in this technique, so we are probably better than the other guys, but everything you will see is at least possible using current UML standards.
• #62: ROI Return on Idea Return on Information Return on Investmernt
• #63: The problem with negative thinking is that it pays off. This is especially true for software projects where the odds of failure are pretty good and negative thinking contributes greatly to errors.Just the act of being negative or contributing negative argument can suck the life out of any Endeavour because the human brain is a bit lazy. The brain is easily swayed by negativity. The brain seems to be wired to filter ideas based on negative attributes. The only time this is not true is when the reward is great. Take lotto tickets. If you can say there is a great reward, the brain gets all googaly. But look at the cost for a lotto ticket. Pretty easy to delude yourself. Other forms of gambling are similar. You usually don’t loose all your money at once, so it is hard for the brain to figure out what is wrong. Negative thinking is just another type of gambling. It does not cost a lot to poke holes in something. Reward is quick too. Most negative comments have no logic to argue against other than the fact that it is a bad argument, so you will usually win unless you are arguing against a true critical thinker. Worse the person arguing in a negative way is not swayed by logic…. How do you think they came up with the negative argument?http://www.internetretailing.net/news/three-strikes-and-youre-out-research-shows-how-buyers-use-customer-reviews/
• #64: One of the great motivators, or rather de-motivators is fear. Fear is subtle. Fear can cause avoidance or action. For example, people that fear pain will avoid things that cause pain. However, people that fear the possibility of pain will often do so without regards to the odds of the pain event or even the scale of pain. Many fear the injection of a needle. The fear is very real, but the pain is often minor and very quick. The fear of pain though could cause you to miss an inoculation or cause worse pain because of a fear of the needle at the dentist. The fact is, as humans we easily go the wrong way on a risk benefit analysis – especially when we don’t closely examine the facts. We get the same problem with methods in software development. Best book on software I have ever read was “The Inmates Are In Charge of the Asylum” by Cooper. It is not a great book, but the insights Cooper had on why software is so bad was illuminating. How many of you have started a project that used a technology that was 12 month old or younger? The fact is that people find less risk in the new, want to pad their resumes, and want to believe in the miracles of new things…. Because they have to be better than what happened in the past. Simply this is all about fear of failure. Most projects fail, so eliminating as much as you can about how you did the old project will obviously reduce the odds of the same failed result, right?
• #65: Another great
• #67: Here we are referring to the requirement itself. There are many other things that can be related to the requirement, but its specification should not contain anything but a clear statement of the need. We can document a requirement to death, just don’t confuse the requirement with its background material. The primary issue is that it is too easy to loose a requirement when mixed with this other information.
• #72: Relationships to other requirements or traces to information that lead to a requirement help show
• #73: Domain – Security, standard functionality, performance, industry standards, languages, etc.Usability – Data validation, help, flow, understandability, etc.Other parts of delivery – Naming, help for marketing, QA, testing, etc.Technology– Required work for use of a technology, etc.Corporate/Industry/Government – logging, security, authentication, metrics, business logic (related to laws or mandates) , etc.
• #74: Evo andPlanguage were developed by Tom Gilb. Evo is an iterative methodology that is very Agile.Evo concentrates on key questions and software metrics. It is a little known fact that Tom Gilb invented the term “Software Metrics”http://www.btt-research.com/rich%20requirements%20specs.htmhttp://gilb.com/community/tiki-page.php?pageName=Evolutionary-Project-Managementhttp://www.livespecs.com/downloads/ClearSpecs20V01_Quantifying%20Quality%20Requirements.pdfSee Also: Agile and Iterative Development: A Manager's Guide by Craig Larman
• #75: From "Rich Requirement Specifications: the use of Planguage to clarify requirements” by Tom Gilb.http://www.btt-research.com/rich%20requirements%20specs.htm
• #77: There are a lot of issues with delivery. Primarily is that scope and priorities change.
• #87: This is one of the really nice things about modeled requirements like we have in SysML. The less room you have, the more precise you need to be. How many of you look at requirements written in Word and can’t actually find the executable requirement?
• #94: No Silver Bullet – Brooks http://www.lips.utexas.edu/ee382c-15005/Readings/Readings1/05-Broo87.pdf
• #102: Plan-Do-Study-Act (PDSA) Shewhart/Deming is a fundamental process for success. Kind of obvious now about our company name
• #107: Origin: John Mayo-Smith’s Information Week article entitled Two Ways to Build a Pyramid.http://www.informationweek.com/news/software/development/showArticle.jhtml?articleID=6507351Rebuttal: http://thedailywtf.com/Articles/The-Great-Pyramid-of-Agile.aspx
• #108: Bex Huff rebuttalhttp://bexhuff.com/2007/05/software-architecture-not-building-architecture