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.

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

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!

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.

John Norman Agile Engineering Leader and Technology Consigliere

June 29th, 2016

Larry, I'll take a crack at this without reading the answers so far, because I would bet that they will break into two general camps: Those who will say that you need a spec because in the medical industry, you want some documents that prove you've built what you intend to build; and those who want to take a more agile approach and build something iteratively.

In my experience, it depends on when you want the spec, what you intend to do with it, and with whom you need to share it. These are all related.

When: For example, were there no development team assigned yet, it might be less costly to have a spec in advance of development. Indeed, a spec might be an incentive for engineers to join your team -- the kind of engineers who fear developing vaporware. The spec might make it easier for the sales team to sell before there's something built.

On the other hand, if you have a development team in place that can build fast, perhaps you would prefer working software and a spec that is generated from that, either manually at the end or (as a proxy) by way of of the automated tests that were written during the development process.

What: Already you can see that questioning the "when" brings up the "what."

With whom: There are cases not covered by what I wrote for "when." For example, if you are a small company working with a big company, it is hard to imagine that BigCo will want to work with you without a spec. I have seen this time and time again. BigCo may even be committed to agile methodologies for their own development, but in a partner, it is scary. So as a part of the contract they may demand a contract up front.

Additionally, there may be compliance issues where you want to get some of your obligations down on paper so that the development team doesn't miss anything. This can be especially true if there are integration points with systems and hardware you don't control.

Your engineering director may be right -- your engineers may not need a spec to write their code. But there may be other business exigencies that demand it.

In my shop, we write specs when we have to collaborate with others, and/or we find that a problem is complicated enough that we want to get some discussion documents up front. When it comes to development, though, we will work iteratively and will not slavishly follow the spec if something interesting comes up in the development.

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

Question stats