User Stories

This post is a follow-up on “Bootstrapping A New Project”

“User Story” is an important communication tool, it is used between you (the developer) and who ever is making the requirements (the stakeholder).
A “contract” which (unlike one written by a lawyer) is clear, understood and agreed upon.
On our side (development) user stories embody a work unit that can be further broken down and estimated.

Key value points:

  • Language - its key that user stories are written in a language everyone can understand (stakeholders, developers etc..)
  • Perspective - user stories need to be written from the perspective of the “feature user”, so they represent real world value
  • Estimation - to help you get better and more precise estimation for the project overall
  • Prioritization - what needs to be delivered soon/later

Lets imagine we just got a call from the product manager, where he is telling us about this new survey tool:

  1. It needs to collect answers from users via a link sent to our users by e-mail
  2. It needs to be summarized and sent to … once a month on the 1st
  3. Managers need to be able to see past surveys

Hmm.. OK, thats pretty clear, but suppose this can be written clearer, lats try using the following template: (not my invention;))
As a [role], I want [Requirement / Feature], So that [Justigication/ Reason]

The requirements now look like this:

  1. As an end user, I will be able to follow a link I got via e-mail, so that I can fill a survey and express my opinion
  2. As a manager, I will receive an e-mail with a digest of surveys, so that I can evaluate performance
  3. As a manager, I will be able to access old surveys, so that I can compare and evaluate performance over time

By reading the above I can clearly understand the required functionality and the motivation behind writing it, this gives me a good starting point.
Since I am the one to implement this, I will need to provide estimates, so that product can plan ahead and communicate the product road map onward.
Unfortunately, “The Devil is In The Details” as they say, so giving estimates based on points 1,2,3 is still difficult.
Points 2 & 3 are “huge” stories, also known as “epics”, we need to further break down these stories, while still using the same language and practices:

  1. As an end user, I will receive an email with a link as a result of some communication with a company, so that I can follow it and fill a survey
  2. As an end user, I get a set of questions to answer, so that my opinion is collected
  3. As a manager, I will receive an e-mail with a digest of surveys, so that I can evaluate companies performance
  4. As a manager, I will have a survey management portal, so that I can overview previous results and compare to
  5. As a manager, I can select a specific survey, so that I can extract meaningful actionable information

The functionality expected of deliverables from the points above is clear, and now I feel more comfortable estimating the time it will take me to complete each.
Along with the estimation, these can now be prioritized against each other and against other ongoing projects..


The beginning of a new project is the perfect time to introduce user stories, it will help with getting the conversation going, further clarifying the scope and requirements.
While the project scope might change, user stories are (optimally) modular, decoupled and encapsulated, this should help with managing changes and their effect on the overall project.

Setting Up IntelliJ For Android And Scala On Ubuntu


Android SDK

  1. get the latest SDK

  2. after extracting, run ./tools/android

  3. from the list select the Android version your afer, right now its Android 4.0.3 (API 15) (I also installed Android 2.3.3), click on Install packages to get the installation started

  4. setup your env echo "export ANDROID_HOME=~/Applications/android-sdk-linux/" >> ~/.bashrc

  5. refresh your currect session source ~/.bashrc

Adding SBT support to IntelliJ

  1. open File > Settings > Plugin

  2. click on Browser repositories

  3. find SBT, right click and select Download and install

Setup SBT

  1. create folder ~/bin/ (if you dont have ~/bin in your PATH, then you can do this: echo "PATH=$PATH:~/bin" >> ~/.bashrc (refresh your currect session source ~/.bashrc)

  2. download sbt-launcher.jar and place it under ~/bin

  3. create launcher: touch ~/bin/sbt and then echo 'java -Xmx512M -jar `dirname $0`/sbt-launch.jar "$@"' >> ~/bin/sbt

  4. make it executable: chmod u+x ~/bin/sbt

Setup android-plugin for Scala support

  1. install giter8 curl | sh

  2. run it ~/bin/cs n8han/giter8

Setup sbt-idea

  1. create folder (if it doesnt exist) mkdir -p ~/.sbt/plugins/

  2. create the file ~/.sbt/plugins/build.sbt and add the following lines to it:

    resolvers += "sbt-idea-repo" at ""
    addSbtPlugin("com.github.mpeltonen" % "sbt-idea" % "1.0.0")

Finally, now that you have all the tools you need, proceed to creating a new project

  1. run the android plugin project setup tool: ~/bin/g8 jberkel/android-app, follow the onscreen questions (or press return for defaults)
    this will create the project folder and create the files needed to build an android project

  2. open the new folder cd <project name>

  3. setup IntelliJ project support sbt gen-idea

  4. open the project in IntelliJ

Bootstrapping A New Project

My take on: How to give your new project a good starting point

So, you have a new shiny project on your lap, so now what?
Today everyone is talking about “agile”, and how its better then the old “waterfall” methodology of doing things


The “Waterfall” approach is notorious in the software community, some highlights of why this is the case:

  • It assumes that the initial requirements will not change
  • There is only one version delivered to the stakeholders, at the end of the process
  • All the planning and “thinking” happen only in the beginning of the project


Everyone likes “Agile”, its the “cool” way to manage a project, it asks for less paperwork, less work upfront, built from the ground up to support changes, to name a few conceptions about it.
While I call it “Agile” here, in reality it is a world of sub cultures, some of which are: “XP” (eXtreme Programming), “scrum”, “Kanban” to name a few.
The difference between specific cultures is not always clear, we don’t necessarily have to stick to one, we can mix and match, like I am doing here, thus from this point onward I will just ignorantly call it “Agile” with out specifying the specific methodology.
The main strengths going for the Agile methodology are

  • Short upfront work phase (requirements, design ..)
  • Iterations - project is broken down to deliverables, which is translated to real value delivered very early in the project lifetime
  • Changes are welcome and expected and are introduced into following iterations (bugs found in previous deliverables, design “inadequacies”)

Doing things in small pieces is great, just ask a WEB developer, how there’s nothing quite like writing a bit of code, refreshing the page and seeing the changes reflected, especially when working on a big complex project. This gives you a feeling of progress and achievement, even though the end goal is far far away..

Some Agile approaches talk beyond writing business code and going into proactive bug searching using TDD (Test Driven Development), which turns out to be a good fit to the overall process as it secures quality of delivered pieces of logic.
BDD (Behavior Driven Development) is very similar to TDD, but instead of going after “test coverage” it takes on a higher level, business specification driven approach, where the business embodied user stories are part of the actual test suite.

My recipe for success

  • User Stories
  • Mock-ups (in the case of an app that has UI)
  • HLD (High Level -system component- Design)
  • Process Sequence diagram / Workflow diagram (possibly atop HLD)


Tools that keep me productive:

  • Google Document (User Stories)
  • Google Drawing (mockups, diagrams, HLD)
  • Lucidchart (diagrams)

In addition, I use a light weight web based project management tool as a central place to keep reference to important docs and user stories, and see my progress (and others working on the project). A great tool for the job is - which free and super simple!


User Stories