Do You Really Need a Spec for Your App?

June 1, 2016

“Specification merely refers to the act of ‘To state explicitly or in detail’ or ‘to be Specific” (From Wikipedia, the free encyclopedia).

Is it really needed in real life, can the work be done after just a briefing?

– You are smart, you can figure out what to do.
– Oh, yes, I’m smart but not a mind-reader.

What You Might Need a Specification For

We hate uncertainty and love when things go smoothly. And when it comes to software products, we like to pretend that we know everything in advance and can write it down. And it’s great because writing down thoughts makes them physical and more concrete, uncovering some gaps that we have not thought of previously. Plus this is extremely helpful when we need to communicate that knowledge to several other people or just make sure the knowledge is not lost after some time.

In this sense it sounds like an absolutely useful thing that has to be on the “Must” list for every software project, until you are faced with the other extreme: a Bible-sized document trying to describe every single aspect of the application, which took ages to create and just a few people will read it (if any).

Before diving deep into a consideration of whether the spec is needed or not, I’ll first provide you with a simple analogy from the real world.

The Story of an Ironman

Meet Eugene, our great dev ops engineer, who loves electronics and stickers on glass walls.

Eugene decided to create an Iron Man after he saw a similar Spider-Man in the other room. Good idea, it just needed to be put into action. Now, that sounds very similar to the beginning of any software story (small mobile app development or complex enterprise system)—we have a concept or an idea and want it to be built.  Awesome—lets go.

IoT project

What’s next? Eugene started thinking about how to get it done and make it nice. He is a smart guy and taking stickers of multiple colors and rushing to put them on the wall does not sound like a good idea; it could result in a complete fiasco and a waste of precious stickers. It all needs to be planned.

See the analogy now? We do not want to jump straight into code without having at least a basic understanding of what we want to do and how we want to do it.

Eugene was not the first one to create this type of art, so some quick googling gave him lots of different images of Iron Man that would look nice with stickers. That still does not answer the question of how to put those stickers on the wall—in which order, and how many stickers of different colors does he need. Ok that is an easy one – he takes the image, gets it down to 50×50 pixel size, adjusts some edges and “voila” you have a sticker-by-sticker plan. Nice! Now he has everything he needs to start putting stickers on the wall. Well … almost everything. “Where do I put that first one and how can I make sure all of them are properly lined up”?

Luckily we have glass walls, which means evenly distributed glass edges that go straight up and form almost ideal lines to start from. So being a clever person with a bit of skill, he knews that he’d be able to put those stickers nicely along the glass lines without too much hassle. Alternatively he could have drawn grid lines on the glass with cells for each sticker, but that is overkill, he did not need to do that.

A Lonely Warrior

As life teaches, even if you intend to do everything on your own, it is better to have a plan. Certainly you might not write anything down and keep ideas, thoughts, and steps in your head. It is all up to you. From my experience  it might be better for most people to unload their mind onto paper. The head becomes free for other thoughts and there is much less chance of forgetting anything.

Would you need a very detailed plan in your head? Probably not. You know what you want, so why would you waste time to make sure you do what you want to be done? Sounds weird…

This is exactly what happened  with Eugene. He was on his own, made his own decisions and followed his own plan. He did not require lots of planning in advance, no detailed instructions on how to do things, but he also did not rely purely on his mind; writing things down helped him crystallize his thoughts and get a better understanding of where to start.

The process looks simple, the result is great, no time is wasted, no unneeded papers written or actions are taken. We’ll use it as an example of a highly effective approach in app development too.

And even if you are not the warrior yourself but decide to hire one, things usually do not get too complicated. It is still mostly a one-to-one conversation and any problem can be resolved in a matter of minutes after discussing it.

Now let’s scale things up…

A Small Group of Warriors and One Trade-off

We can’t achieve much alone, so the point comes when we look for people that can help us get things done. They are enthusiastic about the idea and professional and we get along very well. We found great help.

In this setup all ideas are quickly discussed, problems resolved and solutions found. There is just no need for formalities, process and other waste or writing extensive plan with lots of details. Unless it is decided to keep things in order and under control.

The only difference in this setup is the amount of communication and one trade-off. Either you communicate often or you use other means of sharing knowledge like documents, paper etc.

I’ll hire those warriors

Assuming you did so, you now need to transfer your vision, thoughts and goals to the team. You’ll get them together and explain everything – nice, but does not work. If they are good, they will write down comments and ask a lot of questions.

No questions means you’re in trouble.

Or you may just write down your thoughts/vision and send over a brief, later on combined with an oral explanation. A written brief will provide a good foundation from which to start a conversation. But only the conversation can fill in the remaining gaps.

A Team, But Not Of Warriors

We’d prefer to work with the best but they are hard to find and are expensive. So often it is a question of compromise. We find who we think have the best cost/result ratio. This usually means we’d have to explain more, monitor the progress more frequently, and generally be more in control. You might say, “That is exactly when I’d need to write everything down accurately otherwise there is a high chance of losing things.” And you’d be partially right, especially if you are a lawyer…

But if you are determined to have a great result and not just squeeze it out, having more conversation could be the way to be more effective, instead of trying to write everything down. It gives a much wider and richer context. Plus it is highly unlikely that you will not miss a single thing when writing things down, so a conversation would still be needed.

I’m not talking here about high risk applications that may potentially cause human death or serious outcomes. Most of the software in this world does not control chemical and nuclear plants or planes so even if there is a bug discovered by a user it can be fixed without causing too much trouble. So why would you spend large amount of time planning even the smallest details on paper if it may be faster to prototype or test in real life? But do not get me wrong: I’m not encouraging you to create chaos. Maintaining a healthy balance of things is always important.

Conversation versus text

I hope I was able to convince you that written specification document will not solve all your problems. It has to be accompanied with verbal explanation and conversation.

What is a good balance between text and conversation?

Too much text is not the best thing but a lot of talking can be unproductive too, especially if you multiply the time you spend for a meeting by the amount of people who are there.

My personal recipe is leaning towards organized and planned conversation, combined with a good initial brief and as many written comments as needed during the course of the meetings.

We all know those useless and aimless meetings that have no outcome. Obviously such a approach will not be helpful. But if everybody comes prepared—and usually this means reading whatever materials exist to get a general understanding of what is supposed to be built—hat is exactly when a written brief/intro/story comes into play and is absolutely essential to set the stage. With the clear goal in mind, every participant of an oral conversation usually will know what is expected from her/him.

Same time a brief or even a well-structured discussion do make a plan but do not guarantee that people will not forget what was discussed. So making notes and creating a structured plan with as many details as needed is an essential part of such a conversation.

To sum up

  • Conversation is super important and no document can replace that;
  • Any conversation is meaningless without a well-set goal and it better be written down;
  • You want to have some plan before you start; You can’t do it unless you have a plan;
  • Your plan should be detailed enough that the person doing the actual work would know exactly what is supposed to be done (but usually not how it is supposed to be done);
  • The smarter and more experienced people you have in your team, the less details you’ll probably need to give them upfront, but they’ll still need something to start from;
  • Do you need to spec everything before giving it to the team? There are industry practices and people who know a lot about the domain. But involve Your engineers and let them gather information they need and have it in the way that is most efficient for them. This way you do not need to create spec, just have a good brief for the team;
  • If your mobile app or project is like the Iron Man in our office, I mean if it can be created in a very short time, then it might not be worth it to plan all things in advance. But if you are planning to have all your beloved comic super-heroes on every single empty wall, that might require some planning.

Every project needs a plan, but it is better to plan it with people that will do the work. So prepare your vision and plan it with the team. No need to write long wasteful documents upfront, assuming you can plan for every unexpected bit.