Invest in user stories

Meet Timmy. Timmy is a freelance developer with several years of experience. He has previously worked on small to medium size projects and has a good feeling about his ability to execute.

Meet Sarah. Sarah is head of sales at BigCo Consulting. Since she started at the organization as an intern, they have grown leaps and bounds. She now runs a team of ten people but managing communications within them is becoming unwieldy. She has at best, a vague idea of how tasks she is assigning are getting completed and in what time.

Sarah has heard of the good work that Timmy did for her friend. She believes that her organization would benefit a lot from his services. Seems everyone is making it big in tech this days and she wants in on it.

A kickoff meeting is set off between Sarah and Timmy. Sarah explains that she needs a system to manage her workers more effectively. They discuss about potential features on the product and come up with a list that Timmy is to develop.

  1. Secure authentication
  2. Task management
  3. Accessible from anywhere

This feature list seems good and Timmy comes up with a time estimate and tells Sarah what she needs to pay him. A contract is signed and they both leave the table happy.

One month later Timmy is back with the first MVP done. In the MVP the app enables Sarah to assign tasks to her staff but is still unsatisfied with the product. She can’t really pinpoint it but she doesn’t feel that the app will be particularly useful especially because she could have just as well sent out an email to the team member with the same task.

Sarah decommissions the app having only paid the deposit and leaves the table thoroughly dissatisfied. Timmy feels the deposit paid was barely enough to cover the work done and loses a potential referee for his work. What went wrong?

The curse of knowledge

KRS One has a lot to teach us in the software world. Everyone perceives the world from the prism of their personal experiences. Sarah and Timmy come from vastly different worlds. In Sarah’s mind she saw that she had properly communicated her intent, she assumed meaning to her words were built from the same pool as Timmy’s. Timmy assumed the same.

Unfortunately whilst Sarah was thinking of automating her existing process, Timmy was imagining all the bells and whistles he could build on top of her task list program.

Is there a way out of this conundrum?

The bad news is that there isn’t. The good news though is that we can mitigate it.

User stories

A user story is tool used to capture a description of a software feature from the users perspective.

A good user story outlines specific software feature while keeping all the requirement in a consistent format.

They are easy to write, read, evaluate and dare I say fun.

A user story comes in the format:

    As a ______
    I want to ______
    So that ______

User stories come with goodies that would have saved Timmy and his client from the situation they found themselves.

The goodies I speak of are the characteristics that all good user stories share. They have a convenient Acronym



Good user stories are independent. That is they can be developed separately from each other. By putting the requirements in form of user stories. Sarah would have been able to prioritize the user stories that had the most value to her. This action would have informed Timmy on what Sarah’s actual needs were.


Each user story comes with a non-codable part, the So that _____ bit. That part of the story gives meaning to the requirement. Sarah would have a good platform on which to elucidate not just what she wanted built but why she wanted it built.


Software estimation is hard to get right. You can tell when the leading material on the subject is called Software Estimation: Demystifying the Black Art.

Yet we humans can better estimate smaller components than we can larger ones. User stories enable Timmy to get a more realistic view of how the project is and Sarah to understand the effort required to build her application.


User stories should be small enough to fit on an index card. A side effect of this property is that each story can be developed rather rapidly. The quicker the story is developed the faster the feedback loop between Sarah and Timmy can be closed.


Written in this format, it is fairly easy for Sarah to run the user story through the application to see if it actually meets her expectation (Technically called Acceptance test)

There we go. I am convinced next time, Timmy and Sarah will use user stories to capture their requirements. What about you?


How you pay for technical debt

You are a developer working on a bespoke accounting software for your client. You need to deduct PAYE for the employees when the payroll runs.

PAYE in Kenya currently stands at 30% and for all you know, it has always been like that. So now you have a choice, simply multiply payout by 70% to get the net pay or write out a taxation module with appropriate config files that control what actually gets charged. In the first option you will only spent a minute or so writing the code, the second option obliterates your weekend. What option would you go with? Why?

Like any good consultant if you asked me what to chose, I would say it depends, but if it was my personal choice then second option it is. Now just to be clear I love my weekends as much as any other bloke. But the repercussions for the first decision are way too painful for me to bear. Here is my why.

Unplanned work

As a modern developer, you get to do a lot of planning. From sprint planning sessions to daily standups detailing what you are going to do, plans abound. And why not, planning gives us a special power,it allows us to see not just what happened but also what is going to happen.

Lurking in the shadows is unplanned work.

    Like matter and antimatter, in the presence of
    unplanned work, all planned work ignites with incandescent fury, incinerating everything around it

What is unplanned work?

Unplanned work is when you are late to go to work but you wake up to a flat tire

Unplanned work is when facebook decides to shut down parse and your entire backend is written on top of it

Unplanned work is when you get a bout of the flu during release week

Get the idea?

Obviously some unplanned work is out of your control, but a good chunk of it actually is. That good chunk is the one that arises when you don’t take any steps to mitigate project risks.

You see risk does not play nice, if you don’t actively attack it, it will attack you. It’s primary weapon of choice is….. You guessed it, unplanned work.

Flat tire? No problem spare wheel good and ready to go and factored in some buffer time before first engagement of the day

Facebook shuts down parse? No problem you only need satisfy the interfaces you had defined and inject them in lieu of parse.

Got a flu? Your code was always in deployable state with a working Continuous Integration process in production

Is my choice any clearer? You see by choosing the first option I would have let the beast of risk and unplanned work right in.

For one weekend sacrificed doing it right I have mitigated the risk of:

  1. Government changing its tax policy
  2. Client hiring expatriates, they don’t pay PAYE
  3. Client instituting institutional wide deductibles
  4. etc

You can bet that any of the above scenarios is going to cost you way more than a weekend.

By taking the first option you took time on usury. You traded in a small amount of time now for a much bigger amount of time later. On the short term you may be able to get away with it but remember all dues eventually must be paid.


A developers story

Do you remember the first time you started coding? The experience was likely frustrating, having to deal with code that doesn’t work and finding out the problem was a missing semicolon after a whole night of debugging.

But the wonderful moment comes, suddenly it all clicks, statements, constructs, functions all of it! You feel like you can code any application if you wanted to! It is not long before your nirvana crumbles and you have to deal with maintaining thousand line monstrosities!

Then you discover classes. Oh what a wonderful savior! Classes helps you pack up information into neat objects. Maintaining code has never been so easy. Until when it’s not! You see now you have classes all over, most with names like “Database”, “User”, “Customer” etc. But the classes are spinning out of control! Where do I put this new functionality that signs up a user to our newsletter? Is it the “User” or the “Newsletter”?

At this point in time, our knight in shining armor by name Taylor Otwell comes to the rescue. You know what I am talking about right? Yes Laravel. This is the point you discover frameworks. The power provided by MVCs or MVTs for Django is unparalleled. With fancy slogans like

    Love beautiful code? We do too.
    The web framework for perfectionists with deadlines.

Surely you now have landed on the magic elixir that will help you build huge applications in no time!

And guess what, this time they deliver, you are now rolling out apps like crazy and getting paid! That’s all fantastic!

Your reputation as a developer who gets things done has grown significantly. Today you are seated on the opposite side of some seriously monied individuals. This businessmen want you to automate a very complex workflow for their business. It includes everything from payment processing to a full blown CRM.

You can see it all in your mind, the controllers the views the models! It’s all there! So you start coding!

But something is going terribly wrong. Why do you have three separate payment controllers? Does it really make sense to repeat this code there? You can remember something about “DRY” or was it “SOLID”? How do you apply all those?

As luck would have it you land across a conference recording showing a whole new way of thinking. Welcome to the world of design. Suddenly you see the world is much bigger than MVC you now have a rich vocabulary to build your application!

  • Design patterns
  • Architectural schemes
  • Hexagonal design
  • Micro services
  • Command query separation
  • etc

Awesome stuff! Now your code looks a lot more smarter and you are proud to show it!

Finally you have something to show to the client. Call them to the presentation room and proudly show your wonderful creation!

Something is wrong, no one smiling, in fact you note they are glowering at you! What could have gone wrong? Before you have the time to even verbalize your queries the client goes into a tirade. Claims everything you have just presented to them is worse that useless! The functionality is all wrong and the interface simply sucks!

A few meetings later its all clear, during your kickoff meeting you miscommunicated and with all the micro decisions you we’re making, you drifted further and further from the vision that the client had in mind. But now you know what is up, you promise to do better next time.

This time you are not going to mess up, and if you do mess up, you need to know about it quickly. As you are thinking about it, you realize what you are actually constructing is a process, that is something you heard about somewhere, was it waterfall? You google it up and land on something even far more powerful, agile processes!

  • Scrum
  • Kanban
  • Scrumban
  • Extreme Programming
  • Unified model

Awesome stuff!

Now truly you can do almost anything you have the coding skill, the design skill and the process to bring it all together.

Congratulations chap, you are now a senior developer.