Create user stories and supporting ERD

This post is part of a series of posts: From idea to app or how I do an Oracle APEX project anno 2017

In the first post we defined our high level idea of our application. Now what are the real requirements? what does the app has to do? In an Agile software development approach we typically create user stories to define that. We write sentences in the form of:

As a < type of user >, I want < some goal > so that < some reason >

Goal of defining user stories

The only relevant reason to write user stories is to have a discussion with the people you're building the application for. To developers those stories give an overview of what is expected before the development is started in a language that all parties understand.

Some people might like to write a big requirements document, but for me personally I just don't like that (neither to read or to write). I really want to speak to the people I'm going to build something for, to get in their body and skin and really understand and feel their pain. If somebody gives me a very detailed requirements document, they don't give me much freedom. Most people don't even know what is technically possible or what could really help them.


I like this quote of Henry Ford which illustrates the above:

If I had asked people what they wanted, they would have said faster horses.

Now having said that, you have to be really careful with my statement above... it really depends the developer if you can give them freedom or not. I know many developers who are the complete opposite of me and just want you to tell them exactly what and how to build. Same applies to people who have a bright idea, they do know what would help them. I guess it comes down to, use each others strength and be open and supportive during the communication.

User stories for our project

In our multiplication table project we will write user stories for three different types of users: the player (child), the supervisor (parent/teacher) and the administrator of the app.

• As a player, I want to start a session so that I can practice
  
• As a player, I want to practice multiplications so that I get better at multiplying
  
• As a player, I want to see how I did so that I know if I improved, stayed the same or did worse
  
• As a player, I want to compare myself to other people so that I get a feeling of my level

• As a supervisor, I want to register players so that they can practice
  
• As a supervisor, I want to start the session so that player can practice
  
• As a supervisor, I want to choose the difficulty level so that the player gets only exercises based on their learning needs
• As a supervisor, I want to get an overview of the players progress and achievements
  
• As a supervisor, I want to get an overview of the players mistakes
  
• As a supervisor, I want to print a certificate so the player feels proud of it's achievement

• As an administrator, I want to see the people who registered for the app
  
• As an administrator, I want to add, update and remove users so that the database can be maintained
  
• As an administrator, I want to see statistics of the site so that I know if it's being used
  
• As an administrator, I want to notice feedback and suggestions from the users of the app

The above is not meant to be a static list, in contrary, whenever we think of something else, we will come back to the list and add more sentences. So far I took the role as administrator and parent, my son as child and my father as teacher to come to this list. I welcome more peoples ideas, so feel free to add more user stories in the comment field of things you think of. More info on user stories and how to write them you find here.

More on Agile, Scrum, Kanban, XP

Before we move on with what I typically do after having discussed the requirements with the people, I want to touch on some buzz-words. I guess most companies claim they do Agile software development. Most popular Agile software development frameworks are Scrum, Kanban and XP. I'm by far an expert in any of those, but for me it all comes down to make the team more efficient to deliver what is really needed.

My company and I are not following any of those frameworks to the letter, instead we use a mix of all. We have a place where we note all the things we have to do (backlog), we developed iteratively and ship versions frequently (sprints), we have coding standards, we limit the work in progress (WIP) etc.

When we are doing consulting or development we adapt to how the customer likes to work. It also depends a bit the size of the project and team that is in place.

So my advice is, do whatever works best for you and your team. The only important thing at the end of the day is that you deliver (in time, on budget and what is needed) :)

Thinking in relational models

So when I really understand the problem, my mind starts to think in an entity relational diagram or in short ERD. I don't use any tool just yet, a few pieces of paper is all I need. I start writing down words, draw circles and relations, in fact those will become my tables, columns and foreign keys later on. For me personally drawing an ERD really helps me moving to the next step of seeing what data I will have and how I should structure it. I read the user stories one by one and see if I have a table for the data to build the story. I write down the ideas, comments and questions that pop-up and put it on a cleaner piece of paper. This paper is again food for discussion with the end-users.

Here are the papers for the multiplication table project:

Our ERD is not that complicated I would say; we basically need a table to store the users who will connect to the site/app. I believe in first instance it will most likely be parents or teachers who are interested in this app. Every user has the "user" role, but some will have the administrator role, so the app can be managed. We could also use a flag in the user table to specify who's an admin, but I like to have a separate table for roles as it's more flexible, for example if we wanted to make a difference between a teacher and parent in the future. Once you are in the app you create some players, most likely your children. Those players will play games and every game consists out of some details, for example which multiplication they did.

While reading the user stories, we also want some rankings. In the above ERD I could create the players own ranking, or the ranking of the players of a user (supervisor), but it's not that flexible. That is why I added the concept of teams. A player can belong to one or more teams, so I could create a specific team where my son and I belong too, so we can see each others rank in that team, but I can also create a team of friends. The team concept makes it even flexible for teachers, so they can create their classes and add players to a specific class.

I also added a note that instead of a custom username/password, it might be interesting to add a social login like Facebook, just so the app is even easier to be accessed. As I know in Oracle APEX 5.2 social authentication will be included, I will hold off to build it myself for now, but plan to upgrade our authentication scheme once Oracle APEX 5.2 comes out.

So my revised version of the ERD looks like this:

I hope this already gives some insight in the first steps I do when starting a project.

In the above post I didn't really go into the tools to support the Agile software development (as I didn't use it yet), that is for another post.

If you have questions, comments or want to share your thoughts, don't hesitate to put a comment to this post.