Requirements Engineering/het werk/werkstuk/de opbouw
|
'
Werkstuk Requirements Engineering
Onderwijsinstituut voor Informatica en Informatiekunde
Radboud Universiteit Nijmegen
version 18 februari 2022
De inhoud is opgebouwd als volgt.
Introduction
There is not much I say here about the Introduction. The main point I want to make is that the introduction of a report like the one you are producing has a clear functionality: to set the scene and provide a clear context for what follows. This means that it matters what the audience for the report is, what they want, and what they already know or do not know. Be relevant. To be blunt about it: actual bla bla will not be tolerated. An introduction is not just a header with some semi-random entertaining text underneath it. But on the other hand do not leave out essential stuff that belongs in a requirements document even if everybody involves already knows it. So be both relevant and complete. This is sometimes hard, but nobody ever told you it was going to be easy.
Problem statement
This is the WHY bit of the case project, put in a somewhat negative form: what is "wrong"? What should change? As holds for all items: do not hesitate or forget to update this section as the project progresses.
Case analysis
Stakeholder analysis
This includes items like "user demography" (what types of stakeholders (roles played) do you encounter in this case, and "stakeholder list" (actual, named stakeholders, i.e. specific people and the role(s) they play.). If there are only few stakeholders, that's fine; just provide a clear-cut and relevant listing and description of the stakeholders (users and other relevant stakeholders!).
Mission and vision statement
This is a difficult section. It isn’t even all that important, but I want you to have a serious go at it anyway. The information captured in it mostly comes from what [K&G] call the Chief Executive Sponsor (in the case study, that’s probably me), but you should help him/her formulate it and at the very least you should somehow show you really understand it. As to the (often misunderstood) differences between the three items [K&G p56]:
- Mission— What the project will do (close to WHY)
- Vision— What the end product will be (close to WHAT)
- Value— What principles will guide the project members while they do what they will do and build what will be; the main rules of the game played. In particular the "values" are almost impossible to make sense of in the limited context of our course and case study. I am therefore willing to reduce the item to "Mission and Vision".
Statement of work
This is a project management item. Look at the previous years to find a form that suites you. Keep it simple and use it to keep track of how far you have progressed and how much work still has to be done.
Risk analysis
For this, pretty much the same holds as for Statement of Work. Try to seriously describe some risks involved in your project without spending too much time on this. Note that this Risk Analysis is purely about project risks: risks that you do not make my demands within this case project. So it is not about risks inherent in the system that eventually may be delivered.
| # | Category | Risk | Solution needed by | Status | Days lost | Expectancy factor | Risk factor |
|---|---|---|---|---|---|---|---|
| 01 |
Requirements
Use cases
Use case survey
| # | Name | Description | Initiating actor |
|---|---|---|---|
| 01 |
Integrated use case diagram
Individual use cases
Create a Use Case for all of the ones identified in the survey, include relevant business rule(s).
| Use Case: | Name |
|---|---|
| Use case diagram | |
| Description | |
| Source | |
| Version | |
| Basic course of events | |
| Alternate paths | |
| Preconditions | |
| Postconditions | |
| Related business rules |
Domain Model per Use Case
make a ORM domain model that shows all key concepts from the BCoE and alt. paths and their relations
Scenarios
{{aanwijzing|Scenarios are concrete. They are instantiations of the paths that are present in the Use Case.
Scenarios are mostly related to the BCoEs of use cases. A separate scenario has to cover each alternative path and exception path of a BCoE. So there will usually be various scenarios underlying one use case (n:1). Use these to test the various possible paths that a use case may take (tests are not explicit deliverables, but this does not mean you do not have to perform them! They are an important means of guaranteeing the quality of your use cases.)
If possible, do try and keep similarities visible between the structure of the BCoE/Alt Paths/Exc Paths and the structure of their matching scenarios. Also keep terminology/concepts consistent across use cases and scenarios.
If you use a fact-based approach to requirements engineering (i.e. looking at the instance level first), you may actually get some scenarios before you get use cases. Mostly, however, you will come up with scenarios afterwards.
Non-functional Requirements
[K&G] claim that use cases are a good technique for capturing non-functional requirements. I do not agree. It might be possible to use use cases for non-functionals, but it seems to us a bit forced. Indeed, in the examples of non-functionals (the "- illities" etc.), [K&G] do themselves not use use cases. So the main advice here is: keep to the practices recommended in book when it come to non-functionals, but do not formulate them as use cases. You can find much more on non-functionals in the book.
Addendum
Integrated Domainmodel
The complete domain model should contain all concepts and facts that are used in the use cases and scenarios and should be completely consistent with how they are used in them.
Business Rules Catalogue
The business rule catalog as suggested by [K&G] is quite appropriate. You are, however, obliged to semi-formalize the business rules. With your background knowledge, it should be easy to do so, especially if you already have an ORM domain model. Also note that formalizing business rules is often required in other system development and management activities: see the Business Rules Manifesto (placed on the RE website).
Interestingly, ORM is now one of the main techniques worldwide used to capture (formal) business rules, or at least the most basic, elementary rules in a domain.
In general, our suggestion is you that keep to the type of business rules catalog suggested by [K&G, p60-2], but also
- Make sure the terms you use when formulating the actual rules are compatible
with the relevant ORM domain models.
- Use clearly structured, unambiguous sentences language with clearly indicated
logical or mathematical operators like AND, OR/XOR, IF, THEN, NOT, <,+,- , etc.
- Always also include a formulation in plain natural language
Crucially, you only should include business rules explicitly related to some use case you describe. Also, as indicated, business rules may or may not have been explicitly formulated before your analysis started, but in principle, every organization works according to some rules. It is up to you to find and formulate them!
Finally, please do not be confused by the "business" in "business rules". Perhaps a better, more general term would be: "domain rules". They describe in considerable detail what should and should not be done in the organization (the environment in which the system-to-be-built will function, and which it will support). For example, consider a library. A general rule could be: "items borrowed have to be returned within 21 days from the day on which they were lent out, unless within 21 days from being lent out the loan is extended by the person borrowing the extended". Next, there may be rules that define when extension is possible or not, and so on. Note that all meaningful concepts in the rule have to be included in the DM of the use case(s) to which this rule is relevant, and also that for the rule to be properly modeled as a business rule, some semi-formalization will be required. Creating a DM for the rule is a good way of starting semi-formalization.
Terminological Definitions
We expect all important terms in the use cases/domain models to be properly defined. ORM models do not define terms as such: they provide highly contextualized type- level descriptions of which terms occur, for example as "cats hate dogs". ORM diagrams say nothing about what "dog" or "cat" or "hate" mean as independent words. For this, terminological definitions are required. Together, these definitions can be called many things, e.g. dictionary, glossary, lexicon, vocabulary, ontology, terminology, and so on. We stick to the latter word: terminology.
Our minimal expectation for the terminology in your requirements document is a list of key terms (preferably, all terms that also occur in your domain models) and clear and useful natural language definitions with them. You can use existing dictionary definitions if you like (please provide source references), but do be careful: standard dictionaries have many limitations and they may not describe the exact meaning of some term that the stakeholder actually means/uses in the UoD. Often, it is much safer to write your own definition that is specially aimed at the specific context you are working in. If necessary, get information form stakeholders. After all, both you and the stakeholders can be expected to know what they mean with a certain word; if not, work on it.
Traditional term definitions have a simple format: a definiens (that which is defined), a genus (the "supertype" of what is defined), and one or more differentiae: what distinguishes the definiens from other subtypes of its supertype. So for example, a dog (definiens) is an animal (genus) that can bark (first differentium) and wags its tail a lot (second differentium). Please note that these relations could be expressed in an ORM like manner, but that would go too far since terms like bark, wag, tail etc. probably do not as such occur in the UoD. So simply keep to the traditional definition in natural language.
In particular in the field of Business Rules Specification, there is a brand new initiative to find ways to better specify and communicate about the precise meaning of rules and terms. This initiative goes by the name SBVR: Semantics of Business Vocabulary and Rules. You could say it encompasses terminiological definitions, ORM, and rules. For a brief introduction to SBVR, see the SBVR-1 file on the RE website.
