Maybe it’s just my personal experience, but I have only ever worked for one company that actively committed to writing functional and/or technical specs when developing software. Chances are that you’ve probably had the same experience in your career and perhaps you might even be anti documentation altogether. Personally I don’t think there’s anything wrong with coding without a spec if you’re working on your own pet project in your spare time, but on the other hand I’m a strong believer in writing a spec for formal projects. So before I begin making my case, let’s just quickly define what a formal project is vs just a hobby or pet project.

• Formal project: A formal project differs from a pet project in the following ways.
  • Money: You’re getting paid to develop the software.
  • People: You’re not working by yourself, but in a team with other developers, managers, project owner and customer/s.

I’m going to use an analogy to make my point: developing software without a spec is like travelling from Cape Town to Cairo (10 134.8 km)  without a map. Instead of spending some time looking at the map and planning out your trip before leaving, many people are under the impression that the time spent planning is better spent travelling. This theory would work well if the road between Cape Town and Cairo is a straight line, but unfortunately it is not. Along the way there will be thousands of decisions that will need to be made. Without a plan you will take many wrong turns costing you a countless number of hours. If you had planned out your trip, you would know exactly which turn to take before you even arrive at an intersection.

• Benefits of writing a spec: Here are the main reasons for why you should be writing a spec:
  • Managing budget and timelines: If you’re winging it without a plan you will never be able answer questions in terms of how far you are from the destination or how much more petrol money you’ll need. In the software world this translates to not being able to answer the customer when they ask how far you are and how much it will cost to deliver the software solution.
  • Avoiding scope creep: managing the scope of a project us really nothing more than managing the customer or project owner’s expectations. The spec serves as the scope definition and without a scope you will experience scope creep where the customer gets more than what they’ve paid for, while you and your team will suffer financial losses or at the very least negative cash flow. Aside from the financial implications, not managing the customers expectations and scope of a project, also results in chaos and stress, which obviously nobody enjoys.

Imagining people reading this, I can just hear the millions of excuses for not wanting to write a spec or any sort documentation. So below is a list of common excuses I’ve heard for not wanting to write a spec, and a counterargument for each.

• “I don’t have anything against writing specs, but I see it as a luxury not a must-have. Unfortunately, I don’t have the time to write a spec because we’re running against a tight deadline.”
  • Counterargument: Continuing with our Cape Town to Cairo analogy, in the software world, the spec is your map which you can use as a reference on your trip to software excellence. For this reason, an hour spent planning your trip will spare you taking hundreds of wrong turns, and therefore of will save you days on your travels.
• “Writing a spec is only useful when your developers are monkeys i.e. where you need to explain every little thing to them in detail. My developers and I are all very intelligent. Hence, we’ll just figure things out as we go along because we don’t need anyone else telling us what to do”.
  • Counter argument: This argument is essentially saying that we’ll just wing it. Continuing with the above analogy on travelling from Cape Town to Cairo, this false argument is equivalent to saying that you don’t see the point of planning your trip because Cairo is North of Cape Town and therefore you just need to head North and you’ll figure out the rest as you go along. Again the problem with this strategy (or lack thereof), is that it doesn’t matter how smart you are since you still don’t know what you don’t know i.e. even if you’re heading North, you won’t know what to do when you hit a T-junction. Instead you’ll rely on luck going either left or right and just hope that there will be another road somewhere that will get you back on track towards the North.
• “A spec is just a piece of paper/document, it doesn’t actually do anything. Aside from using it as toilet paper, it has no other uses. Therefore it adds no value to the project.”
  • Counterargument: A spec is not just a piece of paper/document, it is a contract between you and the people you’re developing the software for. The objective of the contract is to manage expectations in terms of what the customer is paying for vs what is being delivered. You cannot meet expectations if you don’t know what those expectations are and failing to meet expectations leads to failed projects, negative cash flows and perhaps even your company closing down.
• “I’m a creative type and therefore don’t like being constrained by a spec that forces me to develop the software in a specific way. Instead I like to think out of the box and prefer having the freedom to come up with more innovative ways of doing things on the fly.”
  • Counterargument: this one really comes down to your level of technical skills and knowledge i.e. whether you’re a junior or senior developer.
    • Junior Developer: If you’re a junior developer then chances are that you not quite read to make design level decisions on software that falls in line with the customer’s requirements. In such cases it would be better for a senior developer/analyst to write up the spec and for you to follow it religiously. If you feel that you can contribute with alternative solutions, you should make the suggestions to the senior that wrote the spec. At this point, the merits of your alternative approach should be discussed in an open minded fashion where you are taken seriously. If you can prove based on facts that your solution is a better one, then your solution should in fact be implemented. Otherwise the senior developer should provide you with a solid fact based explanation as to why your solution would not work in the given context.
    • Senior Developer: If you’re a senior developer and feel that you’re constrained by the spec given to you, then you should bring your suggestions to the analyst/developer that wrote the spec. Better yet, if you feel that you are capable of it, then you should probably be the one writing the spec. Reason being that having a single person designing and developing a system is a lot more productive that splitting the tasks between multiple people. This avoids having too many cooks in the kitchen. Either way, being the creative and agile type is not an excuse for not designing the software and thereby writing a spec before coding.
• “The person writing the spec is only a systems/business analyst with limited technical knowledge of how software is actually developed. That means that their spec will be inaccurate and the software that I develop won’t match the spec anyway. So what’s the point of having a spec written anyway?”
  • Counterargument: This is a very valid point and I have in fact seen this scenario play out several times throughout my career. The solution to this problem can be solved in one of several ways:
    • Teach the analyst: Spend some time explaining what can and cannot be done and just generally bringing them up to speed on the process of software development. This simply comes down to managing expectations, not only between you and the analyst but between the analyst and the customer/end user. Educating the analyst is key for managing this scenario. Of course there are many cases where certain types of people are not open to learning or are simply too arrogant to accept help or advice.
    • Find another analyst: If you have no luck in teaching the analyst, you probably have no voice but to find another more competent analyst. Due to politics and also not wanting to hurt people’s feelings, this could end up being easier said than done. However, provided that you have tried everything in your power to remedy the situation, you will be left with no other alternative but to find a replacement.
    • Do it yourself: In many cases, simply replacing the analyst is not always possible, such as in cases where they are your boss or perhaps due to politics. In such cases, it’s best that you take over the design work by writing the spec yourself. Don’t bother asking for permission, just get it done as it’s easier to ask for forgiveness than to ask for permission. If you  delivery the solution successfully, you probably won’t have to ask for forgiveness anyway. The bottom line here is that whichever way you end up doing it, you still don’t have an excuse for not working with a spec.
• “Documentation is for business people. I’m a technical person and I just don’t enjoy reading or writing documentation. For me the code is the documentation. If anybody wants to understand what the software does and how it does it, they just need to read through my code.”
  • Counterargument: It’s all good and great to say that you understand what the software does by reading the code, but what about the business people that cannot read code, how will they understand what the software does or is supposed to do? Furthermore, think about how long it will take another developer to reverse engineer the business logic out of the code. The point being that you have to think about more than just yourself, and instead keep the whole team in mind. This is a prime example as to why people still pay for software instead of using open-source because most open-source project lack documentation i.e. it’s all good and great to get free open-source software, but it turns out to be pretty useless if you don’t know what it does, how to use it and/or troubleshoot and fix it when necessary.
• “It’s better to write unit tests for defining and validating requirements. Writing unit tests serves the same purpose as writing a spec by forcing you to think abut the requirements. Furthermore, it has the additional benefit of enabling you to also test your code, which is something that a spec cannot do.”
  • Counterargument: This is a comparison between apples and oranges. Unit tests and documentation are two separate things which serve a different purpose. This is the exact same false argument as the one above which implies that unit tests, which are in fact code, serve as documentation. Once again the rebuke on this argument is that code is not documentation since it’s incredibly difficult to reverse engineer business rules out of code.
• “Nobody ever reads specs anyway.“
  • Counterargument: This is a people problem not a technical problem and therefore the people need to be dealt with. The easiest way to deal with people that don’t read the spec is to simply reply to their questions by saying “Check the spec, on page X” or even just “RTFM”. Sooner or later those people will take the hint. The moral of the story is that you need to teach people how to treat you which is to respect the time and effort you’ve put into writing the spec.
• “Even if specs get written, nobody ever updates them, which renders them useless in the long run.”
  • Counterargument: Firstly, who’s fault is it that the spec doesn’t get updated? This argument is equivalent to saying that you won’t take a shower every day because you’re just going to be dirty the next day anyway. That is obviously nonsense and once again this is a people problem not a technical problem. The simplest solution is to become disciplined by getting into the habit of updating documentation on a regular basic.
• “Working with a spec would make us too rigid, and requirements change anyway. Hence we prefer using XP and/or Scrum to manage requirements which allows us to be more agile.”
  • Counterargument: Yes, it’s true that requirements change, but regardless of whether they change or not you will still need to define the the scope of the project. Changes can still be handled in an agile way by using Change Requests which can be filed when new requirements are introduced. What’s important to remember, regardless of what methodology you chose to use, is that no customer or company that you work for will ever give you a blank cheque to spend countless number of hours developing software with no end in sight. Therefore wanting to be agile is no excuse for a lack of documentation and design.
• “The software we’re developing is really large, will take a really long time to develop and as such it is not possible for us to design and document every little feature months or years ahead of time, due to the fact that things will change in the future.”
  • Counterargument: again is the same argument as the one above in terms of looking for flexibility and agility. Indeed it is a valid argument that one cannot predict what will happen months or years in advance. However, you should be able to predict what will and should happen a month or two in advance. I’m not saying that you should write a ten thousand page spec for the development of a two year long project/product. There’s nothing stopping you from breaking down the software into features that should be delivered in the next month or two and then further breaking it down into weekly XP sprints. However, you should write a spec for each software component/feature that you plan on delivering. In other words instead of writing a spec for a complete product that will take two years to be developed, you should write a spec for the first few features that will take two months to be developed. Thereafter the documentation can be updated with the next set of features that are planned for the next two months, thus enabling the documentation to grow and adapt organically as the code does. The point being that the documentation can adapt to changes just as the code does, but the spec and design for each feature should still be completed before any code is written.

In summary, I’m going to throw the age old proverb at you by saying that “if you fail to plan, you plan to fail“. When all is said and done, it really is that simple and there really are no excuses for not writing a spec when working on a formal project or product.