I'm drawn to MSpec with the hopes of one day sharing my test reports with non-developers*, but that is most valuable (right?) if I discuss the business (the user experience) in the test/scenario names (instead of the individual C# objects/members actually under test).
But I'm struggling, with my low-level functionality, to cite non-developer concerns in my test/scenario names. The farther the concern is from the UI, the more difficulty in naming the scenario such that it both a) is relevant to the non-developer and b) describes the low-level functionality being tested.
As you move farther and farther from the UI, is there a point at which test/scenario names just can't be shared with non-developers? I feel like the answer should be "no", because I shouldn't be testing behavior unless it's something the non-developer cares about, but I'm failing regularly enough that I'm not sure what I'm missing.
If there are obvious answers somewhere, I'd appreciate some citations/references.
* e.g. end users or other stakeholders ("stakeholders" might include future developers -- or me in a year and a half -- using these specifications to gain insight into the why of the system)
We normally use the word "scenario" to describe full-system, user-POV scenarios.
If you would like a word to describe class-level behaviour, try "example".
Your examples will be from the points of view of the users of your class. If those user classes want particularly developer-centric behaviour, then, yes, your examples will end up with developer-centric concerns in them.
Having said that, here are some vocabulary changes which I've found let me phrase the value I'm looking for in the most business-oriented way I can:
returns -> tells me or gives me
calls -> delegates, asks
handles concurrency -> handles two things at once
extends -> is a
implements -> performs the role of
Basically, if you're using a developer-jargon word, imagine explaining it to someone in a few more words, then use that.
I wouldn't go overboard with it, though. The reason for using the stakeholders' domain specific terms in scenarios is because stakeholders are interested in reading and (hopefully) writing them. The audience for the class-level examples is technical, so it doesn't matter so much if we have technical concerns in them.
Related
Craig Larman states that creating an Actor[/User]-Goal list in form of some table/grid is a good technique for finding Use Cases during Requirements Analysis. (Applying UML and Patterns - P. 69 ff)
Some simple two-column table should be enough to provide a good Overview for this example; imagine following Actor-Goal List:
Actor Goal
Admin Create User
" Read User
" .. (full CRUD)
" CRUD Entry
" Assign Entry (to User)
" ..
User Create Entry
" .. (full CRUD)
" CRUD himself?
" ..
Admin can do what User can + more like managing the Users of the System under Development or assigning Entries to them.
Admin and User clearly are sharing some Goals(Can we use the term Use Case yet?).
Im not really sure where to go from here in terms of refining this Actor-Goal list.
My brain tells me that i can spare time and effort by reusing/abstraction here, so I will most likely end up with one common superclass implementing the CRUD Entry behaviour, where Admin is extending the functionality by the Manage Goals(CRUD User, assign, etc.).
But I know that this is rather a question of Design than Analysis.
I also know that I can write the Use Case for this in isolation: I dont have to state who exactly uses it, I just need to know that it's some entity which is adhering to the given contract[/interface].
When is the time to start thinking about abstraction?
Am I overcomplicating things by doing so right now?
Should We leave the Actor-Goal list like above and check it off as a "complete" Artifact?
Since the classical purpose of an Actor-Goal list is to provide some quick overview for our next Artifact - the Use Case Diagram - could we begin the transition right here?:
The Use Case Diagram makes the whole reusing part much more visible (at least to me). Would it be advisable to adopt the redundancy right now and take care of it during later stages (e.g. design)?
Appreciate your input!
EDIT: Also I'm not quite sure about the User CRUDing himself.. But lets keep things simple and stick to the main question.
It's an excellent idea to identify the candidate use cases in an actor-goal list, as you have described.
The issues when identifying use cases
In the real life, you'll quickly encounter consistency issues when elaborating the list during requirement elicitation :
some interviewed users/business experts will describe very detailed step by step goals (corresponding to system functions), whereas other will describe rather high level goals user goals. So you'll need a third column to identify the goal level of each use case.
terminology and user goals will not always be expressed in an homogeneous way. So cross checking, and renaming of use cases might be required. For example, I had a system where:
an admin claimed to manage authorizations, and a business user claimed to manage authorization. Was it the same use case ? No: it appeared that the first maintained assignment of authorizations in the system and the second was empowered to decide on authorizations assignment and request them from the admin.
a purchaser explained that for a purchase order someone has to register a good receipt before the invoice is paid. The warehouse clerk explained that at warehouse they manage stock movement. Latter, though, it appeared, that those movements where good receipts, good issues, and stock transfers.
So a fourth column for comments about main variants could help to keep the overview, and to spot hidden sharing potential.
There is generally a great deal of cross checking and harmonization to be done before sharing/reusing use cases. Reusing too quickly might end up loosing more time than expected.
The use case diagramming
I will now be very provocative: once you have the nice and consistent table with all the actors and use cases, what will be the benefit that you expect from a use case diagram ?
It is generally recommended not to abuse use case diagrams for functional decomposition (see also here). So the use case diagram will add little more to what you already have in the list.
In addition, <<Include>> , <<Extend>> and generalization relations should be used scarcely because they tend to quickly make the diagram difficult to understand.
Finally, does abstraction and reuse really happen at the level of the use case ? Is this relevant to the actors outside of the system ? If not, it's more about design and implementation details. So I'd suggest to consider these more in the class model that you will create (or derive) to implement the use cases.
JBehave is Java based & good for Java applications. JBehave also supports good HTML reporting. However, the problem with JBehave is that it only supports Story level and not Feature level.
Can any one here help me with a small explanation or documentation where I can understand how Cucumber supports Feature level?
A feature is an implementation of a capability (a capability might need more than one feature).
Let's look at Mike Cohn's description of a "story", since it's pretty good:
User stories are short, simple descriptions of a feature told from the
perspective of the person who desires the new capability, usually a
user or customer of the system. They typically follow a simple
template:
As a <type of user>, I want <some goal> so that <some reason>.
A good user story follows the INVEST principles, and this is where we start getting into scenarios:
Independent, which means it can be delivered on its own
A story may have one or more contexts in which the feature is going to work. The contexts are by their nature independent of other contexts.
Negotiable, so you can rewrite it
As you work through a story, you may find other contexts or outcomes that need to be considered. The capability which is the core of the feature is usually associated with the "when". For instance, if I wanted to be able to generate a report, the "when" would be, "When I generate the report..."
Valuable, so it delivers value to stakeholders
There may be several stakeholders with different outcomes. For instance, sending an email to say that a cab's been booked is important, but so is sending the booking confirmation to the driver! By considering different stakeholders, we come up with the outcomes for the scenarios that need to be considered.
Estimable, so you can estimate the size
If you can't estimate the size, try just getting one scenario working. This is the functional equivalent of Kent Beck's "spike". Incidentally the only reason you need an estimate is usually to work out whether it's worth doing, given other work that could be done, so treat this accordingly.
Small, which (quick edit as I realised I missed this letter) means you should have some level of certainty about it.
I actually prefer people knowing they have some level of uncertainty about it, and look to get feedback ASAP. If you're really certain about it (eg: login) then it's OK for it to be bigger, because you'll need feedback less frequently; you know what "working" looks like.
Testable, which means the related description must include enough to test it
Examples become tests as a nice by-product of this analysis.
Why do we do stories in the first place, though? Why not just deliver whole features?
It turns out that the work needed to get some features shipped ends up being pretty big, especially if you've got a lot of stakeholders involved, and we want to either slice them up so we can get value from them earlier, or we want to slice them so we can get feedback.
So a story might be a slice through a feature that can actually be shipped, or it might be something designed to get feedback.
Scenarios are a fantastic way of doing this! The feature can be narrowed down to the most valuable contexts, or different stakeholders whose outcomes need to be considered. Be careful not to eliminate stakeholders with transactional needs (the user at the ATM gets their money; the bank debits the account) or regulatory needs (the bank makes a major investment; the regulators see the change in capital reserves).
Scenarios aren't the only way of getting feedback on a feature. New UI? Hard-code it without any behaviour and show it to people. New report? Make up a mock copy. New feed that nobody's ever processed? Make a spike, see if you can get the information out of it that you think you can.
Otherwise, consider different contexts and stakeholders whose outcomes need to be considered, and consider different capabilities with their contexts and outcomes. Features implement the different requirements, whose behaviour is illustrated by the scenarios you've derived.
Since a story is a slice through a feature, and a feature implements a capability, this is a typical hierarchy:
Stakeholder
Goal
Capability
Feature
Story
Scenario
If you're trying to work out how to relate scenarios to stories and features, this isn't a bad way to go. You'll find it familiar if you look at Gojko Adzic's "Impact Mapping" or Matt Wynne's "Example Mapping" (I think we all got it from listening to Chris Matts).
Be careful because in reality this is a bit fuzzy; you'll make discoveries as you start to deliver, so don't break everything down ahead of time. I find capabilities make good planning-level artifacts, and are often associated pretty easily with "Epics". They also come with their own high-level tests: "Can our users do what they need to, for the contexts we need to consider, and the stakeholders whose outcomes are also needed?"
The trick with a story is to only consider what's needed to deliver value, until it's actually delivered... and then some of the rest will be the next thing that's needed, etc.
For more ideas, here's my blog on capability-based planning and lightweight analysis, and another one on splitting up stories.
For Cucumber, organize by capability and then (if you need to) by context, and tag your check-ins with the story number (most CI tools, electronic boards and version control systems support this). It's OK for a feature or story to create more scenarios.
I'm taking a UML class at my school, and my teacher wants us to do the basic, bare-minimum of the assignment, and will not answer any questions. That being said, the requirements of the system had use-cases of Registration, Student Record, Log-In, Course Record, and Class Record. All it really needs to do is the following:
A student will log into the system and the only thing they can do is
register. In the register page, it would list courses available, a
student would select one or many and then they would list the classes
available for each course. The student's records have to be checked
to verify that they meet the prerequisites.
A registrar can log into the system and they can not only register a student but also view and modify course records, class records, and student records.
Also, the classes can be either online or on-site and I'm wondering if that should be defined...
I can provide more detail if it's needed to understand.
Well, I think I took it too far, and I supposed I wanted opinions on how to go about determining the basic requirements.
I also have a couple questions:
Is a Log-In object required in an SRS? Or should it simply be assumed that the users have logged in?
Regarding cardinality and multiplicity, is it the same concept?
Looking at what I've made my multiplicities, did I make any remarkably obvious errors?
As far as making it less complex, would it make sense to only have: class-type, course, class, registration, student, and registrar?
A systems requirements specification is by far more complex than a simple diagram. There are many ways to accomplish a SRS, so your question is a candidate for being flagged off-topic as being too broad. Anyhow, here is what I did.
In a first step you need to group the requirements themselves. The first broad division is by separating functional and non-functional requirements. Non-functional are those requirements which can not be pinned to a single function. Eg. performance, legal, safety, security, you name it. Those are the categories you build first and eventually you have a set of them in the course of the SRS creation.
Grouping the functional requirements is a bit more tricky. You do that by synthesizing use cases. Each functional requirement needs to be realized by a single use case. You don't need to put in details for the use cases, but only a rough story. But once you have connected all functional requirements to use cases your SRS will be ready.
Note that the non-functional requirements are not yet related. This is because they have impact on a lot of functions and the system design in later phases. It's only necessary to have them clearly structured.
Another thing to note is, that requirements themselves should be traceable to their origin. That means you need a reference to the paper, meeting, phone call, personal talk, etc. from where you got it.
There are many, many details which make creation and maintenance of a SRS a science of it's own, but the above is your staring point.
A class diagram is not necessarily part of a SRS. It's part of a later design specification.
Now for your additional questions.
Log-in is no business object in no case. It is a constraint derived from a requirement "user must be logged in to..."
see cardinality vs multiplicity
I would simply leave away the .. notation. If left away it means just the same (unspecified). I'd remove the 'Log-in' word from credential manager since it will also handle log-out and much more. So the emphasis is not right. Else the class design is, as said, not really part of a SRS.
Suppose there is a scenario of Users having Tasks. Each User can either be a Watcher or Worker of a Task.
Furthermore, a Worker can file the hours he has worked on a given Task.
Would the following diagram be correct? I have looked around at domain models and I have not seen one with the two associations (works on, watches). Is it acceptable?
EDIT: What about this scenario? An User can make an Offer to another user. A possible way of modelling it is shown on the following diagram.
However, in that diagram it would seem possible for a user to make the offer to himself. Is it possible to model some constraints in, or is this handled further down the development line?
It is in principle correct, this is how you model multiple relationships between two classes.
As for the constraints, UML makes use of OCL (Object Constraint Language), so you can say that the associations are exclusive (xor - exclusive or).
Also note that it is generally a good idea to name the end roles of the associations.
Regarding one of the comments saying
There are no UML police to flag you down for being "unacceptable".
It is like saying: there's no code police to flag you down for writing shitty code.
You create diagrams to convey information (for school project anyway), if you diverge from standards or best practices you make it harder for other people to understand your diagrams.
And just like there are linters (jslint, ...) that check your code for common problems, for models there are model validations that do the same thing.
Also models, just like code, aren't set in stone so don't be afraid to modify them when you find a better way to express your domain.
Update
As Jim aptly pointed out, you usually do stuff not as a User (or Person), but as a Role. E.g. when you are student and you are filling a form, nobody cares that you are human, but that you are a Student. Typically a Person will also have several different roles (you could be a Student and a TA, a Professor, etc.)
Separating it in this way makes the domain much clearer as you are concerned only with the Roles, and not the people implementing them.
On the first model, there's not much to add after Peter's excellent and very interesting answer.
However your second diagram (in the edit section) does seem to give a true and fair view of the narative. From the strict 1 to 1 relationships, I'd understand that every user makes exactly one offer to one other user, and every user receives exactly one offer from another user:
"A user can make an offer to another user" implies a cardinality of 0..1 or *, not 1.
From this we understand implicitly that not all users need to receive an offer, i.e. also a cardinality of 0..1 or *
This can be debated, but "an offer" doesn't in my opinion mean at "at most one offer", so the upper bounds of cardinality shouldn't be * and not 1 to show that every user may make several offers and receive several offers.
As you can see, you can add constraints to the schema to increase expressivity. This is done in an annotation between { } . But you can choose the most suitable syntax. Here an example with the full expressivity of natural language (as suggested by Martin Fowler in his "UML distilled") but you can of course use the more formal OCL, making it {self.offerer<>self.offeree}.
I see #Peter updated his answer before I could post this answer, but I will post this anyway to show you some other tricks.
In general, it is perfectly valid to have multiple associations between the same two classes. However, I don't think it's a good idea here.
You say you want to build a [problem] domain model. I'm glad to hear that! A problem domain model is very important, as I explain in the last paragraph here. One thing to point out is that you want to build a durable model that transcends a system you can conceive. In the problem domain, there is no "User". There are, however, Roles that People play. For example, you mentioned Watcher and Worker. Hopefully these are concepts your customer already has in the "meat world".
In the model you posted, you have no place to hang the hours worked or progress made. You might try an exercise. If you had no computer, how would your customer track these things? They often have (or had) a way, and it was probably pretty optimal for a manual system.
Here is how I would model my understanding of your problem domain:
Some things to note:
A Person plays any number of Roles.
A Role is with respect to exactly one Task and one Person. A Watcher watches exactly one Task, a Worker is assigned to exactly one Task, and any kind of Role is played by exactly one Person.
A Role is abstract, and its subclasses are {complete}, meaning there can be no valid instance of a Role without also being an instance of a subclass.
A Task is watched by any number of Watchers and may be assigned to one Worker at a time. There is a constraint saying {person is not a watcher}. (You can show the OCL for that, but few people will understand it.)
I have added a Progress concept as a way of logging progress on a Task. A Worker makes Progress on one Task. Each bit of Progress has a Description and a Duration. Note that I have not committed to any computational way of representing a Description or a Duration. The designer of a system for this will be free to derive a Duration from start and end times, or ask the user to self-report.
I am modelling a system and i have the following are some of my use cases{appoint teacher(adimin),record grades(teacher), manage students(admin),record attendance(teacher), manage cocurricular(admin)}
I have some problems with coming up with use case steps and use case scenarios.
i have already drawn my conceptual class diagram.
does any one have an idea on how to go about that?
thanks in advance
You may find an article such as this useful.
My way of thinking. You have general description of the use cases, so you know what the system you're building is supposed to do. But those use cases no doubt have lots of wrinkles and special cases. [In passing "Manage Students" seems at a rather different granularity from "Appoint Teacher" susepect you need "Enrol Student", "Suspend Student", "Graduate Student" or some such.]
So your next step is to capture more of the requirements of the system by giving more detail of the use cases. You express that in terms of actions by people and systems. Do you have a system context diagram or some such? This would show everything your system interacts with. You then express your scenarios as a sequence of actions by actors, your system and other systems.
The Teacher logs on
TheSystem presents a menu
The Teacher selects "record grade"
The System presents a list of classes taught by the teacher
The Teacher selects class
etc.
The wrinkles come from considering the variations that might occur. Any special actions for failing grades? Restrictions on grading for certain types of students? So you create additional scenarios for such "interesting" cases.
In my understanding, at this stage specfic classes and class diagrams are not needed. Later you can consider one step such as "The system presents a list of classes taugh by the teacher" and consider how the system implements that using your class diagram.
Remember the objective here: get the complete picture of the requirements you need to satisfy.
Additionally, although you may not need to do this in class (sounds like a class you're taking), another useful step in requirements gathering is identifying the misuse cases. That is, you want to figure out what bad things could happen in your system. For example, a misuse case could be someone hacking into the system, and then you could write out the steps you would take to correct such a misuse case. Just something to think about.