Lesson Outline

How do we get things started?

In a waterfall approach, we might typically spec out the entire application design. We might create schemas for databases, class diagrams for the application structure, sequence diagrams, technical documentation, and a whole range of other things. Basically everything the system will eventually do, just "on paper". This forms the basis of our agreement with the client, and off we go.

But it ends up being a waste to design the entire system in a lot of cases, because it inevitably changes throughout the life of the project, and we have a lot of wasted work. We gain a better understanding of the system we need to build when we are building it, designing the entire thing upfront is difficult (impossible).

So, we don't want to do that with an Agile approach... but what do we want to do? Do we still create some documentation? Diagrams? How do we actually create this "Product Backlog"?

User Stories

As I mentioned earlier, Agile isn't "prescriptive" so there is no definite way to do this, but a feature that is common across most Agile software development processes is the creation of user stories that form the basis of the product backlog.

User stories are a specific format to informally capture the desired features of an application from the perspective of the end user(s). The main purpose of a user story is to specifically define how a particular feature is going to provide value to that user. If we can't justify the value it is providing, then we might need to revisit whether that feature is really required or whether it needs some rethinking.

A user story takes the following format:

As a [role], I [want to], [so that].

For example, if we were building out a time tracking application, we might have a user story that looks like this:

As a fiction writer, I want to be able to record how long a particular writing session has been ongoing, so that I can create reports for my publisher documenting this

An important aspect of this is that the user story comes first and it is what helps drive what we build - we focus on the real world value the feature provides. It's important not to work backwards. For example, we don't want to anticipate that this application should have some particular feature, and then write a user story to justify that feature. This then just becomes a pointless dance, we have already decided what we want and are just writing a user story to fit in with this format we have created. If we anticipate that certain features are needed, then we should have conversations with the relevant stakeholders, and have them describe how that particular feature would provide value.

This can be a bit of a tricky thing to get used to doing, because some requirements break the mould a little. For example, we might have some security or privacy requirement that we know we need to build. Let's say our time tracking application needs an authentication system and we want to make sure we only store hashes of user passwords on the server.

This user story would not be how we go about this:

As a fiction writer, I want my account's password to be stored securely, so that if data from the database is exposed it won't compromise my password

In most cases, this is likely going to be a complete fabrication. We are working backwards and concocting a user story because we know we need this feature. If the relevant stakeholder really did request this, that's fine - but don't just pretend that a particular user wants something. Not every user story needs to be written from the perspective of the user of the time tracking application, although this is often the case, but sometimes other people will want specific features in the application for other reason.

I find the easiest way to think about this is just to be honest. Who really wants this feature and why? Creating the following user story would be perfectly valid:

As the developer, I want to store users account passwords securely, so that I am following an ethical approach to protecting people's sensitive information

If a user story would require too much work to complete in a single sprint, then it is important to break it down into smaller user stories that could be completed in a single sprint.

These user stories will then form the basis of our Product Backlog. The general process from eliciting requirements to actually working on something will look like this:

1. Talk to the relevant stakeholders
2. Capture user stories (you do not need every user story right away)
3. Sort the user stories by priority into a formal Product Backlog (again, talking to stakeholders)
4. In the sprint planning stage, choose one or more user stories from the product backlog (generally one of the highest priority items)
5. During the sprint, create an E2E test that captures the functionality of the user story
6. Work to satisfy that test

We will be using Test Driven Development for the example application in this module, but technically you can leave that out if you like.

This is not something that we will really be utilising throughout this module, but in the context of user stories it is also important to be aware of epics and themes. These can help provide additional structure around our user stories, especially if we are working on a much larger project.

A theme or initiative identifies a large area of focus that may span an entire organisation - its probably easiest to think of this in the context of a large company that develops software like Apple or Google. This is the highest level of abstraction that might include large plans or goals like "Decrease serve costs by 10%" or "Release a suite of project management tools".

An initiative will then be defined by a collection of epics inside of it. An epic is broader than a user story, but more specific than an initiative. The epic should help drive towards the goal of the initiative. If the initiative is:

Release a suite of project management tools

Then an epic within than initiative might be:

Build a Kanban board for project managers

Then finally we have our user stories. This is just what we have already discussed, but if we were also creating epics then we would categorise our user stories into the epics we have created. This ends up looking like an organisational chart:

We have very few initiatives, some epics, and lots of user stories. If the project is small enough, it probably isn't worth considering initiatives or epics. When working on a smallish client application like we will be doing, we could basically just consider the entire project as one single "build the application" epic which consists of all of our user stories.

Planning and Documentation

Once we have our user stories we know what to build, but do we need to do any more planning first? Create diagrams to show how certain features are going to work?

As we mentioned before, with a waterfall process it would be much more typical to create class diagrams, database schemas, sequence diagrams, and other modelling diagrams right away. We want to plan out everything before we begin coding.

With an Agile process, this is going to vary. We are not going to design everything right away, we might design nothing, but we will probably do something in between. This sort of advice is hard to follow because it is vague and changes.

Within the Agile world, we call things like this "artifacts". A class diagram, sequence diagram, and the product backlog are all examples of "artifacts" - basically any sort of information/reference/documents we have that will help detail what we are building. You will likely create additional artifacts throughout the life of the project, but how much do we need to get started?

For me, I try to consider what is immediately useful. If it is not immediately useful then I won't do it. If it becomes immediately useful later I will do it then.

At the beginning of the project, before we get started, that might mean creating a proof of concept or theoretical diagrams to illustrate how a core feature might work. If there is a question around the idea we have even working, it is important to test it right away before we invest any more time. However, if we will be creating a user roles system at some point, that's probably not something we need to create documentation for right away. There is nothing novel there, and we can consider the exact implementation details when we get to it (and maybe by the time we get to it the project will have changed to not even need a roles system).

So, we might create some diagrams before we get started (or maybe we don't), but what about during the project? What about when we get to implementing our roles system, do we create some diagrams then? Again, my rule of the thumb is "is this immediately useful?". If this is going to be a standard/simple sort of implementation then it might not be useful to create diagrams. If the implementation is going to be more complex, then maybe it will be useful to spend some time planning.

Remember the principle from the Agile manifesto:

Working software over comprehensive documentation

Again, this does not mean that documentation is bad or that we don't want it. But it should be helping you achieve the goal of creating working software, we shouldn't just be creating it for its own sake.

We are going to get into some practical planning in a moment as we start our example project, but I'll give you a heads up now on the artifacts that we actually end up creating before beginning the project:

• The user stories/product backlog
• Two sequence diagrams to plan out how some novel functionality will work
• A proof of concept application to verify the process outlined in the sequence diagrams

As you can see, this is a pretty minimal set of artifacts to create. The main goal here was to verify that the core idea that I had for the implementation wasn't flawed.

In the next lesson, we are going to start taking our first steps toward starting our example project.