Product Design · Product Development

Are spec documents still necessary for software development?

Richard Pridham Investor, President & CEO at Retina Labs

Last updated on February 26th, 2017


Larry Shiller

June 28th, 2016

Whatever software development methodology you use, without documentation you won't have a good way to know if what you built is what you want - whether it's a one-week sprint or a 3-month development cycle. It is possible that your partner is an "information hoarder": Someone who values the knowledge they have that no one else does. If so, having sensitive antennae along with intolerance for information hoarding behavior will result in better outcomes. If your partner insists on not documenting, shorten the sprint cycle to a few days to minimize your documentation debt.

Anthony Miller

June 28th, 2016

Hi Richard!

Sounds like he is referring to agile software methodology, which we run on as well. We write out all of our stories and then assign them to our dev team, each story has its own weight. Based on the amount and weight of these stories we do software releases every 2 weeks. But to have it all in his head and to not hold sprint planning sessions every week with the team seems too loose. You need to have an overall product vision and be able to understand which features you'll need to have ready for this big date in October. 

Sounds like this person may also be a little inexperienced. I'd be worried that you won't hit deadline for this MVP. Best thing you can do is tighten things up. Understand what can be done in the amount of time you have available to you. Make sure you have your roles and process down before starting or you may see them not able to hit these small interation deadlines.

Hope this helps.

Ilya Stametau Senior Software Engineer at HubSpot

June 29th, 2016

There are a bigger issues here: 
 - your partner wants autonomy, respect, and doesn't want to be micromanaged.
 - you don't trust your partner and, as a result, seek more control.

Work these out first. Build rapport. This will either make or break your venture. 

Good luck.  

Andrea Raimondi Computer Software Consultant and Contractor

June 28th, 2016

A spec is both necessary and useless :)

It's necessary because it gives you that "clarify your thoughts while trying to figure out what to build and how" and useless because - in the end - no product on Earth ever resembles its specification document :D

Tim Scott

June 28th, 2016

Boy, there's a lot of daylight between comprehensive spec document and "all in my head." You don't want either. What you want is some kind of agile process.

Some 15 years ago a few smart developers began to articulate why Big Up Front Design (BUFD) is the hallmark of failure. Your specs document sounds to me like BUFD. BUFD is typically an exercise in make-believe, pretending you fully understand the problem and how precisely code will solve it before you begin development. The design document is treated as a contract, and all kinds of pain ensues. Been there done that.

Your guy talks about rapid iteration, so maybe he has some agile process in mind. But "all in my head" ain't it. That's called cowboy coding. Any agile process will involve formally writing down every single thing you intend to build before you start building it. The difference between agile documentation (typically in the form of "user stories") and a "specs document" is that you do not try to fully delineate every feature in the system up front. You do that before each iteration (perhaps 2 or 4 weeks). Also, you don't treat user stories like mini-contracts but as placeholders for ongoing dialog with product owners (e.g., you).

There's a lot more to say about agile process. There are tons of tools, books, training, user groups, etc. Don't get hung up on details or tools. It can all be done on index cards. But insist on a process that includes user stories or something similar.

Also, there's nothing wrong with writing down specs for particularly complicated business rules or doing wireframes or mock-ups. Just don't try to pretend you can can full articulate your specs in the form of a contract before coding begins.

Michael ★ CEO & Founder - Launchocity | Agile & Lean Startup Consultant | BYU-Idaho Alumni Mentor | Avid Entrepreneur | CSM, SA

June 28th, 2016

Hey Richard,

I appreciate the other thoughts here, but I think there are a couple of things that are missing. First, your goal is an "MVP", so that needs some clarification. Second, the idea of what a "Spec" is has changed.

"MVP" = Minimum Viable Product ="[the] version of a new product which allows a team to collect the maximum amount of validated learning about customers with the least effort" -- Eric Ries.

Couple things to point out here:

1) Where this term has been popularized is in the book "The Lean Startup" by Eric Ries and also by Steve Blank. Lean Startup has become a foundation for innovative product development which, while it has roots in Agile, is more specifically focused on answering the question, "what should we build", via validated learning utilizing the scientific method.

2) The terms "Validated" and "Viable" suggest that you have already answered basic business questions about your product (e.g. who are our customers, what problem are we solving, how much will they pay). In Lean Startup, these questions are typically found on a "Business Model Canvas" or, what I like to use, a "Lean Canvas" which was created by Ash Maurya who is also the author of a great book "Running Lean".

3) Since your goal is to deliver an "MVP", this suggests you may not yet have the validated answers suggested in item #2. If you do have those answers, then you should have those documented (and they'll likely look like specs, which I discuss next).

Note: If your tech guy really understands what an MVP is, then his goal may be to get those answers via his suggested iterative process, which will ultimately result in an MVP. In order to get there, he has to start validating something, so let's assume that he's planning on starting with the ideas/plans that are in his head, which we're going to call a "hypothesis", which brings us to specs.

"Specs" = requirement specifications = documented requirements (functional, technical, etc.) that will satisfy an expected end result.

Couple things to point out here:

1) Traditionally, these are heavily detailed documents that require a lot of work prior to development and have been used as contractual agreements between "the business" and "development". (Don't do this!)

2) Agile contends that you make a lot of assumptions in a traditional development model that don't typically pan out well as far as hitting the mark where customer value is concerned. Assuming that your goal is to provide real value, and that you don't know what features that requires, Agile suggests using an "iterative" approach to building a product where, on a regular "time boxed" basis, you develop working features and then meet with the end user to discover if you hit the value mark or not. Specs in this model are only as good as your assumptions and often change throughout the process, so it isn't very valuable to fix, in a "traditional" way, what it is that you are going to build, rather you need to be accepting of change (hence the name, "Agile").

3) Lean Startup takes Agile's approach one step further and suggests that you don't actually need to code anything to start validating your assumptions (hypotheses). It offers a method that is much "Leaner" than even a typical Agile approach, which will lower your upfront investment until which point you have a validated MVP. Specs really don't come into play early on here since you're not necessarily coding anything. Rather, our hypotheses are quickly invalidated, in which case we "Pivot" to a new hypothesis, or we've "validated" them to an acceptable degree. After we have validated several of the earlier mentioned business questions, we then will likely have something that resembles lean version of a traditional spec, to which we can build! And the set of specs that will come out of this process will ONLY include the Minimal set of requirements that will make the initial Product Viable!

To sum up, look into the Lean Startup and understand what a MVP is. Then, make sure you and your tech team are on the same page as far as how you are approaching the important issue of creating real customer value, including how you validate it, and what a "spec" for you should be. Finally, be prepared to be involved and help during this time, especially if the basic business questions haven't yet been answered. Hope this helps!


Michael Moore

Jesse Merl President Gatsby TV

June 28th, 2016

Depending on budget, my suggestion is to hire a qualified CTO if the software effort is going to be a critical component to your business moving forward. You can use contract development as long as you have someone in house owning the build, leading, and managing the contractors. With contractors you will definitely want to build out requirements and spec docs but your CTO will handle that. Don't try to be something you aren't and learn as you go. I learned that one the expensive way.

Robert Lasky Digital Executive, Consultant and Cross-Industry Channel Expert

June 28th, 2016

The short answer is yes, you still need a spec so that your partner and you agree on what's being built for the MVP, and so your partner can develop the sprints he's referring to in order to get there (sprints are the short iterations he's referring to). Without that, you're both introducing a lot of unnecessary risk.

Typically, sprints are one or more stories developed in a 1-2 week cycle. Semantics aside, stories provide the same value as requirements. You probably have to agree from a business standpoint, your partner from a technical standpoint, and the developer from an implementation standpoint. At the end of a sprint, it's black-and-white... Was the requirement built? Does it work? Etc.

There are a couple of major problems with the head of development keeping specs in his head, aside from it being a sloppy way to handle development:

1. If he steps off the wrong curb, you're done (sorry for using such a bleak example).

2. It leaves too much room for subjectivity (e.g. he explains casually to a developer, they build and test, he says what was built isn't what he meant / they discussed, you've all wasted and lost time.

There are many problems that fall out of these (politics, culture, etc.) but I don't think they need to be elaborated here.

What you ultimately agree upon may not need to be exhaustive like in waterfall or iterative development if he's trying to be more agile, but agile is far from a free-for-all.

Good luck!

Howard Cohen Founder/CTO at Point Together, LLC

June 28th, 2016

I’m highly opinionated about this. It write essential requirements and a functional specification down so that they can be agreed to. First I get agreement on the essential requirements, then I work on the functional spec (which is more work). In other words, what is written down becomes the social contract for what will be produced. It is the contract between those who develop the product and all other stakeholders. It isn’t always easy for engineers to write; however, it is an investment that protects you and your chances of success. And, the essential requirements are not hard to write compared to functional specifications. The cost and time investment is low for producing essential requirements, and the return on that investment is higher than any other kind of document, in my opinion, because the most serious misunderstandings are eliminated before they even waste time in the functional specifications! I believe software projects should be run *transparently* ( Let me put this another way… If they can’t write it in plain english that you can understand, what makes you think they can write it in a computer language? English is far easier because you can rely on previous knowledge of the audience, and people’s tremendous intellectual capacity to learn concepts while reading a document. Computers are utter morons by comparison. Communication with a computer must be precise and so it must be predicated on a fairly precise understanding of it is supposed to do. It should be far easier to convey that understanding in English than in a programming language. It costs a small fraction to write the specs compared to the cost of the equivalent software. I would never accept a software project as a programmer without supporting specs (even if I write them) so I can be certain my customer/client will be satisfied with the outcome. A focus on requirements first and functional specs before coding ensures that the customer’s needs are met. What I would insist on is this: 1) Collaborative definition of the essential requirements for the project 2) They should respond with functional specifications for your review and approval. I generally expect screenshots or mockups here, for every important screen, and a text description for each and every button and other control. You can test the functional spec for completeness because it should be documenting how each and every single essential requirement is satisfied. If you don’t see an essential requirement addressed in the functional spec, the spec isn’t done yet. 3) You would then negotiate over the functional spec to get a clear understanding of everything. You decide which parts need to be done in phase 1, which in phase 2, which in phase 3, etc. At least you know where the whole product will end up. 4) You size phases so that you meet your goals for functionality, but also for cost and schedule. This dovetails nicely with agile development. Driven from specs, management should be straightforward. But, if it is driven from their minds… you will be powerless. More details about: * Essential Requirements: * Functional Specifications: * Creating a Bid: (good to know when expecting a bid too!) Best of luck, - h

Sean Mitchell

June 28th, 2016

I prefer an Agile approach, with short iteration cycles as well. However, no documents or use cases or wireframes? Wireframes are always useful, even if it is just to get everyone on the same page and identify opportunities or issues that a singular perspective is likely to miss. The tools of web development yesteryear are not obsolete, they are just not always required as once percieved. There is no magic unicorn when it comes to a development process. I have seen a waterfall and pure agile work just as well as one another. It all comes down team dynamics, the target market and the nature of the product itself. In your particular situation, one guy with an idea in his head and two junior (cheap) developers that probably barely have any concept of continuous integration or dev ops or unit tests or scalability or security is not a good sign in my opinion.