Estimation Tool v1.0

So what is one of the hardest problems regarding software projects? There might be a lot of different answers to that question, but here is my take on it.

And yes, it is colored of my disapproval of using tools to solving problems they were not tended to solve.


TLDR;

So this describes the process of developing a central estimation tool that gathers notes, defines estimates, and generates offers, reports, and overviews of the final estimation work, done by a development team.

The central things this paper will touch upon are:

  • Stop using Excel to gather notes regarding estimates - use a proper tool or make your own.
  • Communication should be central, not estimation numbers only.
  • Make sure to frame the estimate to communicate the context of the estimate.
  • And for Petes sake, stop providing estimates without proper requirement gathering, framing, assumtions, and limitations specified.

On a technical note, it also showed that writing documentation on methods in code, is a valuable thing. It forces the developer to think about the problem, the responsibilities of a class or interface, and to validate that the implementation solves the original problem. A kind of eye-opener for me as a developer.

The result (lets get it out of the way)

A walkthrough of the result - hope the link still works

It actually became an almost finished product that basically could support a estimation process within a team of any size. The main screen during an estimation session are the screenshot below - it enables to get a clean overview of all stories and their calculated risks, so you would know where to define your requirements a bit better.

Overview of all stories

All the calculations are based on the configuration defined on the estimate root, it contains the central knobs where the number of developers, amount of time spend on artifact work etc. are defined:

Creation of stories

It would be able to capture all the different perspectives through notes for each of the different resources and finalize it by defining a best- and worst-case estimate. Handle a story

One of the central things in this small project were to make sure you stayed focused on the actual estimate that you were working on. So instead of having the possibility of watching all active estimates constantly, you had to actively go switch to a different estimate and start working on that.

Motivation

So why do you want to write an article about something, as sexy, as estimation? Well - I havn't been in software development for that long, but during those almost ten years, I have seen a bunch of pitfalls in the flow from sale till development.

One of the things are the, sometimes, total separation between technical salesmen/architects, and the actual development teams. It seems like sometimes a project is sold, and the only description that is being given to the development team are a user-story headline, attached with a estimate. This really needs to stop right now!

One of my favorite things that I heard when one of my projects were going over the original estimates were from a salesmen:

But we had a handover meeting and everything, how could this happen? Why didn't we deliver everything to the customers expectation?

First of, handover-meetings are great, but it is not enough. Second of, how do you define what the customer expected, relating to the original estimate, if the estimate were only numbers and a user-story headline? You might be standing in front of a dissatisfied salesmen and customer, but truth be told - you didn't have any chance of delivering true value, if the only thing being handed over were a estimate without framing or limitation.

So how does a lot of companies solve this? It is a pretty interesting thing to read about and talk to people about, because they still tend to solve everything by using the tools they currently have present - and remember:

Don't use a hammer to cook a egg

That is the main issue in this problem: people are still misusing Excel to solve all problems that involve numbers that needs to be added together. And when it comes to estimation, numbers are basically the least of the problems. We all have hate-passions, mine are when you mis-use tools to fit your purpose, when what you truly needed were to build a tool (or buy) that fits your needs.

The true concerns about estimations can be prioritized to the following bullets (if you ask me):

  • Defining the requirements in short, specific terms
  • Framing and limiting the scope.
  • Fill out anything unknown with assumptions, if answers are not possible to get.
  • Put on some numbers through the use of estimation techniques.

The number's part are a very small part of the estimation work. What is truly important is that you capture all the aspects of the known requirements, framing and the limitations.

As a process manager once told me when I started to ask critical questions regarding the estimation excel sheet:

But you are supposed to use the estimations sheet after you have done the refinement.

I get it, you should already have done you business analysis before doing the estimation. And I truly agree... But... The final requirement limitation and framing happens at the estimation sessions between the estimator and the people who are supposed to implement the project. And these details and notes, are the dealbreaker when it comes to the final functionality provided to the customer.

Imagine that a salesperson sold a project to some sort of amount of hours. The sales guy/girl, and the technical architect might have had a bunch of cozy talks regarding what the customer can expect to get our of the deal, and some of that information might also be located in some documentation for the developers to read.

But what if the customers expectation does not match what the actual development team can provide? What if the sales guy sold gold, pearls and dreams to the customer? Do you, as a developer have a chance to succeed? I don't think so...

And that is where notes, assumptions, and framing come into the picture. In the ideal world, the people who will solve the customers task will also estimate it (in the ideal word).

In every estimation session it is the developers responsible to define the frame of the task by writing down all notes, limitations, and assumptions they perhaps have regarding the new task. Before any actual agreement happens, the customer needs to read these notes to accept the given frame - if not, the refinement is not yet done.

And this has nothing to do with the project approach. It is the same no matter if the project is agile, iterative, waterfall or a good mix of all of them - it is all about how often, and when this final refinement happens.

Make sure to frame, assume, define, and explain what you expect to deliver and what you will not touch.

Play with a open hand of cards, and no one will be disappointed at you.

Technical motivation

Enough of the actual motivation for doing this small project. I am sort of a programmer and will properly always be in contact with code - so why not make this a bit fun.

I always wanted to learn some degree of DDD and TDD, so I thought that this might be the place to do it. I had no expectation of becoming a DDD wizard, because that might be a lifetime journey, but at least I should be able to model a problem and make my life a bit better. Likewise, with TDD, I did not want to think about code coverage, but to stick to a quote from the original TDD inventor:

Customers does not pay me for tests, they pay me for working code. I do tests till I have confidence in my code.

Likewise, I have experienced a lack of priority when it comes to documentation of code - which is a touchy subject for many agile developers.

My goal with this small project were to try to write as clean of a project as possible, modelling the domain, creating tests till I had confidence in it... All that (almost) before actual coding and try to document everything while doing all of this.

Project plan (booooring)

You always need a plan... If I stated that I just started coding on the first take, I would lie. It was important to me to match the project with the actual approach you would have when talking to a customer. First of you might wanted to map all the different requirements, goals, hopes and dreams that the customer might have regarding the project... And that were almost the same strategy I used.

This all came down to me defining the following list of requirements to start with:

  • Need to categorize it into groups of tasks - like e.g., an epic.
  • Creation of a task with notes fields and ability to define best and worst case estimates.
  • Define a busines ambition that cases could support and a way to validate that a case were in scope.
  • View the raw data regarding best and worst case estimation.
  • Configuring the estimate regarding amount of developers etc.
  • View the notes taken during e.g., an estimations session.
  • Export of data to old Excel schema.
  • Export of all notes to give to the customer.

Likewise, there were a secondary list of ideas that might bring value in the future versions:

  • Defining of a persona so you could validate that a specific case defined some value for a given class of users.
  • Asking the "five why" questions to identify the business need for a task.
  • Enrich with both diagrams and text pages.
  • Ability to generate a offer containing both list of cases and estimates, but also some additional documents.
  • Mark a case out-of-scope, not just with a low priority, but as something that were not considered a part of the delivery or estimate.

All these things should support the goal of the entire project:

Ensure communication from estimator to development team, and the best possible start for a project - both for the customer and the team members.

Evolution away from Excel

So where did this funny journey start. Well, everything starts with a frustration, a problem that needs fixing - and my problem were that I had no idea, regarding why the team I was a part of, sometimes went over estimate where other teams seemed to keep theirs.

So after asking the project managers and the internal process-team, I found out that we actually were missing some information in our team. The rest of the teams were using an estimation sheet that contained a lot of different factors that covered almost everything that we were missing. We normally just estimated the work needed to be done, but not e.g., all of the communication that had to happen between the different developers.

The estimation sheet itself were pretty simple, it captured the story in a headline, associated it with an epic, and defined some business ambitions that it should support. To that record there were a best- and worst-case estimate field for both frontend and backend estimations. All is good till now.

What made me start to become skeptical were the two columns that were named something regarding notes: one for internal and another for external/customer notes. Putting so much text into Excel is like cooking an egg with a hammer - it does not make sense.

I knew if I had to work in this, I would become mad at some point. And what does a developer do if they are in such a situation - they fix it with programming.

So the game were set, I had to re-engineer the Excel sheet into some code that made sense and could be used to define estimates just as accuratly as the current sheet.

So the Excel workbook had two main sheets, one for defining the very shallow user-stories, with limited notes, and a sheet with a bunch of tables defining the different parameters and configurations to support the calculations. A total of six tables across two sheets. Some of the different calculations took a bit of time to re-engineer because it referenced across both sheets to different tables to come up with the result.

Tech stuff

The good thing though was that tables normally can be translated into domain models pretty fast and easy. This were no exception - so I ended up with the following entities:

  • Ambition - defining the business value you try to achieve.
  • Category - the grouping of stories into e.g., epics
  • Estimate - the best- and worst-case numbers.
  • EstimateVariable - configuration for defining e.g. the numbers of developers.
  • ResourceConfiguration - defining which type of resource should be estimated e.g., frontend and backend.
  • Story - well, a place to keep notes, descriptions and gathering the different resources estimates.
  • ResourceComment - the missing entity from the Excel sheet, a place for each of the resources to define their own scope and notes.

The story of an object

The central entity was called an EstimateRoot. This could have some configurations regarding which resources should be able to define estimates (ResourceConfiguration).

At the same time the EstimateRoot contained the configuration for how big the team were and how much the hourly rate was(EstimateVariable). It also scoped the estimate to define the business values, so it would be possible to verify each story, and determine if they supported the tended ambition (Ambition). To make sure it was split into manageble groups the EstimateRoot also contained a list of epics (Category).

When the estimator started to define the different tasks/stories, he would have to reference it to a given epic, determine the ambition, set the priority, and describe the given task, let the resources determine their own notes, and finally define the estimate.

TDD to a limit

One of the technical aspects I set out to try, where the use of TDD in some aspect. But there are a lot of things you can test in a project like this, right down to getters and setters. The question was, did it make sense? And, at least, my answer was, No! I would not use my spare-time writing test that did not cover something business-critical (in the sense of this small project). So, to limit the scope I chose to use my test-time on the central aspects of the domain model, and testing the services that did the central calculations of the estimate. If I did that, I would have tested enough to have confidens in my small project. So please consider:

Test the central and critical aspects of you code. Don't test everything, and start forgetting about code coverage.

Documenta.... Zzzzzz

I have heard it before, no one wants to write it, no one cares for it, and it is basically outdated right after you have written it. But there is a different aspect of documentation.

What if you could use documentation as a mind-tool? What if the documentation on a method actually helped you to implement the method, and helped you validate if it were actually doing what it was supposed to do? All of this is actually possible if you take the time and write the inline comments on your methods.

I have heard a couple of podcasts that talked a bit about how the "old" programmers (no offense) did their work. And they would not touch code before they have defined the implementation in some sort of pseudo code, or just written it in clear text in a comment. This way their minds started to validate the problem and started to look for errors in the line of thinking. By doing that they removed a lot of errors before going into coding-mode. And remember:

Removing issues and errors before the implementation stage is cheaper than after.

It might seem stupid, but inline documentation and comments can make you code better and contain less errors if you use documentation as a tool to support you - rather than looking at it as a boring task to finish

Future project plan (not so booring)

This small project started out to be a Proof-of-Concept application. I had a certain focus that meant some other aspects of the code needed to be down prioritized. And one of those aspects were storage. I once read an article about Wikipedia (I think), and their history of development. But they stated that they first started to prioritize the storage part of the system late in the process. Their main focus was on functionality, the all data could basically just be in the form of text files on disk.

My focus was the same, I had a lot of thoughts about the functionality and API design that I didn't want to have to worry about the data storage just yet. This way I could develop all the central functionality and test it without having to deal with cumbersome data storage. But if I take this one step further, I guess I need to use some time on actually making this persist to some sort of database.

A different aspect of this small project was to form documents that one could send to the customer for final approval. It should be possible to decorate it with prose and diagrams. So, the thoughts were circulating around the concept of a Document. This entity should be able to have a type, defining if it were a markdown or a diagram.

In the case it was a markdown it should be possible for the user to write in a text field on the left side of the screen and see the preview on the right. Likewise, if it were a diagram. Instead of spending countless number of hours on developing integrations into some drag drop diagram application, then basically use the PlantUml endpoint to render a images based on text input. That way storage was also going to take less space.

When these two types of documents were implemented, the user of the application needed to be able to define a sequence that could look like the following:

  • DOC-1 (Intro to project)
  • FIN-SUM (Financial summary of hours)
  • NOTES (Notes from stories)
  • DIA-1 (Context diagram)
  • DIA-2 (Integration diagram)

Basically, it should be able to generate a report based on the identities from the different entities. That way the user could control the order and information that were generated to the customer. If you wanted to hide all the notes because it contained a lot of uncertainty, then just don't define it in the sequence.

Conclusion

A lot of time and energy have been used to form this very small project. And as a developer I have learnt a lot about statistics, estimation math, TDD, DDD, and in-code documentation. One of the truly most surprising things that I experienced were the part regarding documentation. The possibility to catch a lot of the problems before they are manifested into code, just by writing the comments above your method were truly a dealbreaker. To be able to model the problem and verify it before writing code could save a lot of time, money and energy - this is something I will try to prioritize in my future development.