DEV Community

Ricardo Giro
Ricardo Giro

Posted on

On requirements and their documents

A small preface on unexpected complexity

I remember back in school when learning about RDBs, my teacher asked the class to make a flowchart of how an ATM works (from user approaching it to receiving cash).

The flowchart started small with inserting card, inputting code, choosing cash amount and finally receiving that amount. That's simple enough but hardly reflective of reality as we quickly realised that this simple algorithm is missing critical rules, presented here on the second column.

Function Restriction
Insert card Is card invalid? (marked as stolen, expired)
Input Code Is code correct? If not, repeat up to two more times
Choose cash amount Does account have enough funds?
Receive cash Does ATM have enough cash to give user?

It obviously gets more complex than this! Here is a flowchart I quickly found online (

ATM flowchart

All of this to say that the importance of a good pre-study of the apps main functions, expected behaviour and it's obvious restrictions is very important.
You can't account for everything at the start, but frontloading the obvious can save you loads of time and backtracking.

Creating Requirement Documents

GPT kept telling me about Requirement Documents and how they can help plan out the apps functionality. It suggested using something called User Stories and Use Cases.

Use Cases, used in many fields besides IT, are basically interactions between an Actor and a System to reach a Goal. The Actor doesn't necessarily need to be a user, it can be some part of your app that is interacting with something else.
User Stories aren't much different but are seen/written from the users point of view. They are usually informal and describe a need that a hypothetical (or real) user has that they want the app to fulfil. There's more to it but I think I'll stick to the basic.

I'll also simply list requirements and things I think matter in the document.

Making the Req Doc

I won't go into much detail but the document is a series of lists that have some basic information on what I want the app to do, as well as things the project itself must explore!

  • Baseline functionality explained through bulletpoints, use cases, user stories, etc

  • Authentication and Authorization: ASP.NET Core Identity for role based access

  • Database: using MariaDB and the Entity Framework Core. We'll get into schemas later!!

  • Statistics and Graphing: the app must have a section where it shows stats and graphs to the user. GPT recommended Chart.js or Google Charts

  • Unit Testing: I have veeeeery little experience with testing but it is something I have to use all throughout the project. Will look into xUnit.

Top comments (0)