4

Throughout this semester my classmates and I had to do the pre-coding(?) phase of a project (requirements and such) as part of our Software Engineering course. The way our professor had us do it seems odd to me and I'd like your input.

First we were given a document with the problem and had to extract requirements from it into a Word document. The project was about the software for a parking lot. That part didn't seem so weird to me, but then we had to fill in a bunch of other things in this Word document which would later be called "report" (at this point it was just called "Component 1"), such as a context that is a grid with this format:

enter image description here

enter image description here

enter image description here

This Word doc also had a "change history" which we never ended up using. This report also described the software, the client, the quality and functional requirements, the restrictions, and the drawings.

These drawings are pencil sketches of some functionalities of the software, ie creating an account, with all the steps. Here are my drawings (the first one is a user profile and the 2nd one is a blueprint of the garage with the sensors and zones):

enter image description here

enter image description here

Then we had to make a "detailed version of the requirements" in an excel document. This contained things like a glossary, actors, objectives of the Organization (ie making money, using SCRUM, expanding to the EU), objectives of the Software (ie functionality), links of real software we took inspiration from, and then the fun part: User Cases, UC scenarios, UC steps, entities and entity attributes.

User Cases: Describes user cases. Its columns are things like the objective it relates to, main actor, other actors, pre-conditions (ie there must be entries in the database, internet connection), post-conditions (ie the printer prints something), priority, importance (idk what the difference is between this and priority), UC scenarios it participates in. We had to fill in, by hand(!) over 50 rows. Most of this was just copy-pasting and changing the name and the description.

UC scenarios: Scenarios wherein the UCs are used. Examples:

  • Creating user profile: success
  • Creating user profile: cancelling (user clicks the cancel option)
  • Creating user profile: exception (incorrect data is inserted)

This particular part had over 100 rows which we had to fill, by hand. Most of this was copy-pasting with little editing. Columns include again pre-conditions (what UC it was part of, basically, which was repetitive), post-condition (ie. UC is cancelled), results (ie an error message is printed. Not much difference from post-condition and as we couldn't figure out the difference we kind of made it up), and UC scenario steps it relates to.

Now the worst part.

UC scenario steps: For every UC scenario (there were around 110) we had to describe the steps. For example:

  1. User clicks "create account" - Type: System call - next step: 2
  2. User inserts data - Type: Data introduction - next step: 3
  3. User clicks "Submit" - Type: Data submission - next step: 4

3b. User clicks "Cancel" - Type: UC cancelling - next step: ... ...

And so on. We filled more than 500 rows of this, by hand. It took a considerable amount of time and most of this was copy pasting.

Then the entities. Our professor told us "Imagine how the data will be inserted in the database, the entities are the tables and the attributes are the columns". And that was basically it, only we couldn't repeat attribute names (ie. the vehicle ID in the User table as it already exists in the Vehicles table) for some reason. Something about it "already existing in another entity".

Me and a group of classmates from the Msc who have already completed this class were talking to a professor of another class and he asked us what we did in this class and we told him what I wrote above (we all had the same experience) and he laughed so hard at us he almost started to cry, which was quite funny to be honest. He said no one does it this way in real life, that this is all automated, and found the part about the pencil sketches particularly funny.

He said that nowadays everybody uses agile methodologies which have nothing to do with this. To be honest through the whole semester I could never understand what methodology we were using. It looks like some variation of RUP, vaguely, sort of? It's agile-ish because we'd go back to earlier steps and complete them in steps afterwards and we could change the requirements, objectives and other things over time (which our professor insisted we did so sometimes we'd just make up stuff) but this doesn't look much like the agile methodologies I've studied in class.

On our last evaluation I told the SE professor this wasn't normally done in real life because there is software that does the excel stuff for us, and she insisted that it was impossible to automate this completely, and that because our requirements were from a problem statement and not interviews we had to do it this way (I assume she meant there were no user stories?), that this is how its done and told me to "get some real life work experience" and then get back to her. She said that requirements engineering is supposed to be repetitive and I said that a lot of the stuff we did could very easily be automated and that it was hard to believe nobody had done so until now, and she insisted that no, it was impossible to fully automate this process and that many things still had to be done by hand, and then told me that when I learned how to sum in school first I had to learn how to do it by hand, to understand, and only then did I learn to use a calculator and this was the exact same thing (so which is it?). I commented that it didn't seem to me that teams used excel and word for requirements in this way irl and mentioned SCRUM and backlogs, and she insisted that while many teams used different methodologies than hers, this process still had to be done and many do it this way.

I felt it was better not to insist and afterwards I got a long winded email from her that one of the reasons our work was so repetitive was that we repeated a lot of the same scenarios and steps in the UC scenarios steps bits and that irl there is "more variety" so it's "less repetitive".

One more thing: In one class our professor told us we could make this more "KANBAN like" by adding a column called "progress" in our excel and writing whether a particular requirement/objective (she said those were different things but the difference was lost to me) had already been finished or was in progress.

My question is, what is this methodology we used? Is this even a thing?

How is this done in real life?

2
  • 3
    In real life this is often done differently but that is not always a good thing. Mind that the main purpose of your method is to allow your professor to track what you did, not to deliver usable software. Jun 18 at 17:27
  • While it's true it's not done that way in real life, that's because real life it's often done dumber and more haphazard Jun 20 at 1:43
6

On an OOP conference in Munich, ~20 years ago, I asked one of the speakers (Chris Rupp, author of several books about requirements engineering) which tools she would recommend for collecting requirements. As I remember, she answered "The most frequently used tool in the industry for requirements engineering is MS Word, closely followed by MS Excel". Note this was coming from an experienced consultant with lots of practical experience from several IT companies.

What I know today is - this hasn't changed fundamentally since then. Of course, certain people prefer to use Open Office, Libre Office or Google docs / Google sheets today, but still word processors and spreadsheets. Those tools are ubiquitous, every IT based organization equips their employees with them, and almost any kind of conceptual work can be started with them immediately.

Beyond this, today there are tons of project management applications, ticketing systems or CASE tools available where requirements can be collected, categorized and prioritized in some kind of database.

However, regardless of the tool, and regardless of the "agility" of the process, what matters most for requirements engineering is the content, not the media. And the core content of a requirement is always written as plain text or text in tabular form (sometimes supported by diagrams, UI sketches, or references to other documents, all things which can be perfectly captured in a text document or spreadsheet document).

So when learning about requirements engineering and systems analysis, I think the most important things are

  • how to interview people and interpret what they are telling you so you can distinguish what they say literally, what they mean with these words, and what they really require,

  • how to extract requirements from domain specific documents,

  • how to write down requirements in a clear, understandable and unambiguous way, tailored for the right audience (which are often users, stakeholders and developers),

  • how to detect hidden requirements which are worth to be written down, even if the people you interview don't mention them explicitly,

  • how to decompose larger requirements into smaller ones up to the degree they can be implemented,

  • how to keep the evolving list of requirements consistent, orthogonal and free of conflicts, and

  • how to do all of these former things effectively, without wasting time for framing, without writing down unnecessarily redundant stuff, and without diving way too deep into details of a potential implementation.

From what you wrote, the course given you by the professor was suitable for training all of the non-interview points, with one blatant exception: the last point.

Now don't believe replacing a word processor or spreadsheet by one of the other applications I mentioned beforehand would solve that problem. Database founded tools show their value in larger teams, and in organizations where requirements have to be managed over a long period of time. They can help you to categorize requirements, prioritizing them, keeping them well structured, managing related documents, connecting them to certain people or integrate with other parts of the systems' life cycle. What they definitely don't do is making it easier to write down the right stuff, or using the appropriate level of abstraction.

Quite the opposite: word processors and spreadsheets have the huge advantage of not imposing a specific structure on any requirements documents by themselves - technically, you are completely free to design your own document templates (except for the cases where some professor insists to make use of theirs). In my experience, they are pretty suitable to for trying out different ways of writing down and structuring requirements, way more than any specific tool which forces you to write requirements in a predefined standard form, which will sometimes fit, sometimes not.

So as an example, if there are >100 UC scenarios, most of them having commonalities, in a word processor document you are free to add an introductory paragraph to the use case section and describe the commonalities once, at the beginning. In the description of the individual use case, one can focus on the specific parts of the individual use case - maybe with a reference to the initial paragraph, but without repeating redundant stuff in a cumbersome manner. As you see - no "special software" is needed for this, no "automation".

And that is what indeed happens also "in real life", at least in companies or organizations where requirements engineering is done in an efficient manner:

  • word processors and spreadsheets are used heavily (but some other tools as well, often in combination)

  • the documents are tailored to the specific environment and needs of the organization

  • business analysts and/or requirements engineers will have a real audience for their documents, so they can work out interactively with that audience which document structure, format, or level of detail suits them most

  • most detailed requirement descriptions are related to already existing systems, and describe expected changes to that system (which requires usually a lot less boilerplate stuff than trying to describe a fully new system from the ground)

  • in economically driven companies or organizations, there is usually a large business interest to keep their processes efficient, which includes software engineering and requirements engineering as well. Hence in most of this organizations, analysts will not get a reward for producing documents other people cannot effectively work with.

Both of your descriptions about your two professors' points of view, however, seem to show a certain lack of practical experience with requirements engineering outside of the academic world. But that is probably not their fault, they may have a lot theoretical knowledge about the topic, and that's exactly what you can learn from them. Working effectively in this area and getting first-hand practical experience is something you will learn at other places, places where efficiency is a business goal.

6
  • 1
    Side note: this answer has already become longer than I initially expected it to be, and I still feel I could write even a lot more about the topic. However, I guess it is time to post this now and ask you if there are points you would like me to describe in a more detailed or different fashion.
    – Doc Brown
    Jun 19 at 4:38
  • Your answer is good, thanks. What you said definitely makes sense. In the examples from the class PowerPoint the examples even left blank some of the squares where information was repeated but then our professor changed her mind and decided we should just fill everything. I didn't think Excel was efficient enough even though it certainly has its advantages like you mentioned, I just didn't get the message that we could use it as you described. I got the feeling the method we had to use had to be necessarily rigid for requirements to be well documented. Jun 19 at 16:03
  • 1
    @Segmentationfault: normally, you would ask your audience (or at least think about what your audience requires). It also depends on the specific requirement, how it will affect the existing system or the entities in the system. For example, when the system stores a lot account-related data, editing a user account may be a very different operation than deleting one - editing may just mean to pop-up an edit dialog and change a few fields in the "Account" entity. Deleting an account may mean to delete all account related data, or replace all references to the account by an anonymous ID ...
    – Doc Brown
    Jun 20 at 8:01
  • 1
    ... (as you can see specificially here on the SE sites, when a user ID gets deleted). However, for other entities it may not be useful to to separate "edit" and "delete". For example, the comment here which I write at this moment - the "comment" feature on this site fortunately allows corrections, and removing a comment can be seen to some degreee as a special case of editing it (of course, there are still subtle differences, but I guess you get the idea).
    – Doc Brown
    Jun 20 at 8:07
  • 1
    ... it makes also a difference if your requirements document will only be used as a "wish list" for a pre-contract discussion, or as a base for a detailed estimation and project controlling, or as a base for a "Sprint" in Scrum. These different stages may all require different levels of abstraction. So in short: know your audience!
    – Doc Brown
    Jun 20 at 8:10
4

Whenever I hear students complaining about the approach taken by a professor, I advise them to watch Karate Kid 1.

Half of the film is about stupid tasks that a karate professor is making his student do and the student complains that he desperately wanted real lessons to learn to defend oneself. Spoiler alert (but it’s ok the film is 30 years old): Then in a situation of need and stress, the student suddenly realises that he’s able to effectively defend himself thanks to the reflex acquired during the stupid activities.

Requirement engineering is exactly alike. You can of course use directly modern Use Case 2.0 or User Story mapping. You can go kanban if you want. And you can also use plain old detailed use-cases with painfully detailed test cases of your professor. That’s ugly, but in your course you don’t have real users to experiment with other approach either.

Anyway, keep in mind that although you will not necessarily need this rather rigid practice, the underlying ideas are still relevant in many situations. Whether you do an up-front requirement specification in a traditional waterfall or v-model project or whether you elicit requirements just in time within iterations of an agile development, the key competence remains the same: to understand what a user really needs and to express the criteria to be verified for ensuring that the development meets that requirement.

Finally, these rather heavy documentation practices might be required in highly regulated industries where software is known to put millions of lives at risk (e.g pharma industry under GMP obligations).

One thing I fundamentally disagree with your professor is the repetitive character of requirement engineering. Requirements are not guessed out of the blue, but discussed and agreed with customers and users. And this is far from boring and repetitive but on contrary full of anecdotes and extremely enriching: if you want, you can learn everyday something new just working on requirements with users. And in my own opinion, nothing is more rewarding than the smile that means “yes! exacty! finally a person that understood my work” (actually there is: when the same smile remains when the software is delivered) :-)

Edit: Another thing that is not so great although still popular is some circles is what you call the worst part. Not only is this microstep by microstep cumbersome, it is also forcing decision on the design of the user interface made by people who are not necessarily skilled in user interface design and even less in user experience. Jacobson the inventor of UC recommended in his earlier work before Use Case 2.0 to prefer “essential use cases”, where there is no steps but only intents, focusing in this way on goals and leaving UX to experience designers. Try as an exercise to rewrite a couple of your UC using this technique, to understand the difference.

3
  • Even so, in real life combat sports no one is required to do those stupid tasks. Students learn by practicing the actual moves and by fighting. We could, in my opinion, done just a few of the requirements this way and done the rest on software. Maybe have one thing or another that required more specific documentation like in your pharma example. I find my professor's method boring, repetitive and a waste of time for the most part. Jun 18 at 16:53
  • 1
    @Segmentationfault actually, as a former karate teacher myself, I confirm that people learn best by repeating movements over and over again. first decomposing them, then more fluently, then with a partner in a prepared situation and then in real situation with one or several opponents. Muscular memory takes at least one thousand of repeats to make a movement a reflex, and work out the unnecessary or counterproductive muscular contractions. Some students take just a hundred times and show they can do the movement to perfection in the ideal conditions of the dojo, but without the (1/2)
    – Christophe
    Jun 18 at 18:01
  • 1
    @Segmentationfault … insurance that it’ll work when it really matters. But you are right: requirement engineering cannot compare to this extreme conditions. Reflex short circuit the brain for speed. Requirements need the brain to be in full control. So perhaps it was indeed too boring and theoretical and I agree that it could be made more entertaining. But I cannot change it, you cannot change it. My message is to take this situation from a positive perspective and make the best out of it: something in all this will help you later, even if you can’t believe it now ;-)
    – Christophe
    Jun 18 at 18:14
1

From the sounds of it it seems like you are using the Waterfall Model.

This model has the benefit of making you define your requirement, before you start to design your software. The design step is done before starting on the actual implementation.

This way you will learn all the steps one by one instead of learning all at once.

Some benefits is that you will have more documentation of the development proses when you are done.

Penciled sketches are still done, but there are also wireframe software and other types of mockup software that you can also use.

Not the answer you're looking for? Browse other questions tagged or ask your own question.