Are spec documents still necessary for software development?

Richard Pridham Investor, President & CEO at Retina Labs

Last updated on February 26th, 2017

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.

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.

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.

Jesse Merl President AudioBooth

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!

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

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.

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!

Best,

Michael Moore

Launchocity.com

Christoph Ranaweera validate early, pivot and kill fast instead of feeding a zombie

June 29th, 2016

you CEO refers to agile and believes that it's about whouting over the table to the other side what he needs and that the other one (the dev) will understand.

Is not going to work. That's a classical way how you get what you don't want.

Requirements are necessary.

but you want to keep it agile so you don't go scoping out every aspect including technical implementation what database to use and how the requests will be handled - this is to give freedom to devs to decide on that.

You need user stories to see the product from user perspective.

You still need wireframes and mockups which you have to usertest. Your CEO knows what he wants, what each function will do but when you give it to your customers they might be confused and at some points they definitely will. The Dev can't do user experience.

Actually when your partner will put together the stories for the product he will notice already that some more things are necessary or some things don't make sense. Just an idea in the head is ignoring details.

And just to be clear: Agile does not mean without specification it's the level of specification that matters

Question stats