Working software over comprehensive documentation

Cole is a software engineer who is frustrated to software functional specifications. Sometimes there is details which are changing and sometimes needed details are missing. This happens project after project. With heroic last days work Cole can fix the last things and deploy to customers. But soon Cole has had enough.

In this post I’ll take a closer look to a Cole’s problem and why it happens. I’ll explain it based on principles related to software development and get back to the Agile Manifesto.

Principle based problems

I like three golden rules which have been introduced in the book called Agile Samurai.

  1. It’s impossible to gather all the requirements at the beginning of a project
  2. Whatever requirements you do gather are guaranteed to change
  3. There is allways be more to do than time and money will allow

Why I like those rules? Because those are concrete results from the fact that software project is about solving complex or mediocre problems. Think about present days ERP systems. Those are not simple, are those?  (You can find more about this from Management 3.0)

About principles, it’s again like a nature. If you eat too much fat, you will get fat. Damn fat.

If environment and processes are not set based on the principles then there is too often needed hero’s and flexibility. And only after heroes and flexibility there is change that project is success.

Cole’s challenging project

Cole started with the new project. The project had requirements specification done which were gathered by consultant with customer. All the requirements nicely ordered and all the details were considered and written down. “Very nice. Finally something which I can code from start to end without need to interrupt others.”, thought Cole.

Problem 1 – Missing details and missing feedback. After two weeks Cole faced the first problem. Even though document had a lot details, some details were missing. Cole asked about the missing details and it turned out that the answers were not simple to give. Consult were already busy with the new requirements doc (tying to put down every single detail to not fail again) and Cole were able to feel frustration every time they had a conversation.

Cole got the answers but feelings were not high. Cole decided to start to do his own assumptions instead of asking. Cole was engineer and his decisions were more from the technical point of view.

Finally coding was done and system testing started. Consult participated to testing to check that everything was ok. Testing phase showed that some Cole’s assumptions were not correct.

Biggest surprise was that when consult asked to run old interface for data which new functionality produced Cole answered that it wasn’t possible. Cole explained that he used new database architecture for data sets and old interface just didn’t worked on top of that.

Because there was things to be changed Cole and consult decided to move deadline 2 weeks to make things right.

Cole started to be in trouble as the needed changes were not in align with his architectural solution. To make the changes in 2 weeks Cole needed to do shortcuts in the code and in usability. Shortcuts were not enough and he needed to do long days to make it in 2 weeks. Time started to run out and not all testing were able to do all over again.

“Oh why he hadn’t tested my software earlier. She could have seen how I understood what he wrote in specs and I could have adjusted my work and architectural decisions based on early feedback. Now I have a lot of things build on top of things which I need to change” Thought Cole at one long evening at the office.

Problem 2 – Understanding based on concrete results. It was time to show 2 month (and 2 weeks) results to customer. Customer noticed that for getting the value out from the solution they needed to have almost perfect product name parameters in the system. Customer were very sceptic that they could have such complete data in the system in real life.

But they got an idea when they were using the software. If they could just have one new user selection state for their controller for the data which was produced, they could forget the whole product name parameter problem and go on with just 2 extra week coding with Cole. Together with Cole they found out that this last change to the requirements made unnecessary ¼ of code which Cole already produced in project.

“Why we didn’t thought this earlier?” Said customer. “Yes, why not. I could have been home with my wife and kids if you would have saved some of my time and some of your money.” Cole thought.

Cole was angry. Why everybody checked his work results when it was too late for it!

Understand the principles

Cole’s problems in the project are caused by process which is not the for complex problems. Roughly Cole’s project was done like this:


If you really believe that you can find the best solution before a single line is coded you are wrong. A problem solution process in complex or mediocre environment isn’t straightforward. Even though final solution might be simple and easy, path to find solution isn’t.

This means that work with requirements will not stop when development starts. Consults, customers, coders and testers needs to work together. They need to create a teams where customer and development point of views works together for the best implementation.

In practise there needs to be first created guidelines and only then nearest details are thought. Details which are not needed next are waste. When you build small part of the solution for a review, then team understands problem better and might end up with the better final solution. It means that rest of the requirements might and should change based on the new understanding.

Below you can see picture of a process where team works together with observation from the built solution. “What needs to be done” steers “solution building” and “build solution” steers “the need to be done next”.


Working software over comprehensive documentation

So iterative software development with observation makes sense. But it might be difficult to understand before you are able to admit that the software development is about solving complex or mediocre problems. When you understand it, then you are ready to use tools which are developed to handle such problems.

Use working software over comprehensive documentation. If you will not do it, somebody else will. If it’s your competitor, you might lose your Coles and customers.


One thought on “Working software over comprehensive documentation

  1. Pingback: Storytellers in software development | JP Jokiaho

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s