Sign up ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

I know this is holy war territory, so please read the question to the end before answering.

There are many cases where written specifications make a lot of sense. For example, if you're a contractor and you want to get paid, you need written specs. If you're working in a team with 20 persons, you need written specs. If you're writing a programming language compiler or interpreter (and it's not perl), you'll usually write a formal specification. I don't doubt that there are many more cases where written specifications are a really good idea. I just think that there are cases where there's so little benefit in written specs, that it doesn't outweigh the costs of writing and maintaining them.

EDIT: The close votes say that "it is difficult to say what is asked here", so let me clarify: The usefulness of written, detailed specifications is often claimed like a dogma. (If you want examples, look at the comments.) But I don't see the use of them for the kind of development I'm doing. So what is asked here is: How would written specifications help me?

Background information: I work for a small company that's developing vertical market software. If our product is easier to use and has better performance than the competition, it sells. If it's harder to use, even if it behaves 100% as the specification says, it doesn't sell. So there are no "external forces" for having written specs. The advantage would have to be somewhere in the development process.

Now, I can see how frozen specifications would make a developer's life easier. But we'll never have frozen specs. If we see in the middle of development that feature X is not intuitive to use the way it's specified, then we can only choose between changing the specification or developing a product that won't sell.

You'll probably ask by now: How do you know when you're done? Well, we're continually improving our product. The competition does the same. So (hopefully) we're never done. We keep improving the software, and when we reach a point when the benefits of the improvements we've added since the last release outweigh the costs of an update, we create a new release that is then tested, localized, documented and deployed. This also means that there's rarely any schedule pressure. Nobody has to do overtime to make a deadline. If the feature isn't done by the time we want to release the next version, it'll simply go into the next version.

The next question might be: How do your developers know what they're supposed to implement? The answer is: They have a lot of domain knowledge. They know the customers business well enough, so a high-level description of the feature (or even just the problem that the customer needs solved) is enough to implement it. If it's not clear, the developer creates a few fake screens to get feedback from marketing/management or customers, but this is nowhere near the level of detail of actual specifications. This might be inefficient for larger teams, but for a small team with low turnover it works quite well. It has the additional benefit that the developer in question often comes up with a better solution than the person writing the specs might have.

This question is already getting very long, but let me address one last point: Testing. Like I said in the beginning, if our software behaves 100% like the spec says, it still can be crap. In fact, if it's so unintuitive that you need a spec to know how to test it, it probably is crap. It makes sense to have fixed, written tests for some core functionality and for regression bugs, but again, this is nowhere near a full written spec of how the software should behave when. The main test is: hand the software to a user who doesn't know it yet and tell him to use the new feature X. If she can figure out how to use it and it works, it works.

share|improve this question

closed as not a real question by gnat, Walter, Jim G., GrandmasterB, Caleb Sep 8 '12 at 6:14

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.If this question can be reworded to fit the rules in the help center, please edit the question.

It seems a common theme for this profession is that very few things are true in all circumstances. Using absolute words like "never" or "always", etc is usually a shortcut to a "no" or an "it depends" type answer. – whatsisname Sep 7 '12 at 14:57
How new of a developer are you? This question indicates that you really don't understand a great deal about development. If you cannot connect how specifications can be written to achieve "a product that is easier to use" you need to do more research. – Ramhound Sep 7 '12 at 14:58
@whatsisname: That's what I suspect. But specs are one of the 12 commandments in the Joel test, and a lot of people here on PSE treat them with almost religious enthusiasm, so I was wandering... – nikie Sep 7 '12 at 15:13
I guess the problem I have with this question is two things. The first problem its way to long to ask the underline question. The other problem seems to assume a specification document should not be modified as the program is updated through its release cycle. The specification isn't for the custom its for the developers. The specification should specify how the program works, and this often includes, how the user will interact. If one implementation does not satisfy a requirement of "being easy to use" you modify the specification so you can implement something that can. – Ramhound Sep 7 '12 at 15:17
@Ramhound: I wonder if you have ever worked on vertical-market software? If that 50-million dollar contract comes around, and the software we deliver doesn't solve his problem the customer doesn't care what the spec says. He will haunt you anyway. So if that's really the only advantage of having specs you see, then there really is no advantage for my kind of work. – nikie Sep 7 '12 at 15:42

3 Answers 3

When you rely on developers to have lots of domain knowledge, you had better have a plan for making certain that ALL of your developers have ALL of that domain knowledge.

If you don't have that, then losing one of your developers to a competitor, or a soccer mom in a runaway SUV, can really, really hurt your business, possibly fatally. If he was the only one who understood a particular topic, and that topic is important to a customer, you now have an unhappy customer and an avoidable relearning exercise.

Written specifications capture this knowledge. Done properly, they do not constrain the design, and they do not "lock in" difficult-to-use implementation. They say WHAT the product must do, without saying HOW.

share|improve this answer
+1. but FYI, the word "spec" can mean different things in different dev processes. I've been in a process where the "what" was defined in requirements. A design doc restated the "what" with a more technical layout and a very light dose of "how". The actual spec specified the "how" with a light dose of "what". For better or worse. – Lord Tydus Sep 8 '12 at 5:10
@LordTydus, the original question seemed to imply that the "spec" he was talking about was a requirements specification, and that's what I was talking about. – John R. Strohm Sep 8 '12 at 7:49
I guess there are domains where that isn't entirely true however. I have worked on big accounting system projects where written specifications were a recipe for getting programmers who didn't have sufficient domain knowledge to get confused and build something that didn't work. The fact is that written specifications are a collaborative tool but they are not a substitute for domain knowledge. – Chris Travers Sep 8 '12 at 9:20
@ChrisTravers, are you telling me that all of your programmers are required to be qualified accountants, fully familiar with the GAAPPs, fully briefed on all of the Sarbanes-Oxley rules, AND fully knowledgeable and current on all the FASB reports? I shudder at the thought of your annual training costs. – John R. Strohm Sep 8 '12 at 12:30

You are assuming that writing something down makes it frozen/permanent. This isn't always the case.

I recommend reading about waterfall vs agile. For example, in Scrum you do write things down. But only a few weeks at a time. At the planning meeting the customer discusses the immediate future. Things are written down in agile (task cards, sprint backlog). But they are not carved in stone. In fact, you aren't even stuck with those few weeks. The Sprint can be cancelled if need be.

That said, I don't think you should have the "developers just develop based on domain knowledge and dummy screens." Talk to the customer. Which may be you. Or may be market research.

share|improve this answer
Obviously the developers do talk to the customers. How else would they get domain knowledge? What would be the use of dummy screens if you didn't ask the customers questions about them? But the point is: Our customers won't read a 100 page full behaviour specification. – nikie Sep 7 '12 at 15:06
And: Of course we do planning. We write documents that describe new features and discuss them internally and with customers. We do all the things you say. We just don't produce full written specs on the way. – nikie Sep 7 '12 at 15:07

The benefit of a spec to the dev process is understanding what to do. You already have the level of understanding you need so you're good to go.

You also appear to be a product company making [your] solution to a problem rather than conforming to [their] specification. This is one step closer to developing software for your personal use. If you are the customer then you already understand what is needed.

Another case against it is complexity of the software. The software may be so complex that it cannot be specified. For example a facial recognition program which must match a human's ability to recognize faces. The requirements are simple, but the detailed spec is very difficult. It may require techniques no one has ever done before (original creation). It may require constant trial and error experimentation. You find recursion overflows the stack causing significant design changes. It may be best to make a specification after a working implementation is produced.

I often have the opposite scenario. I have no domain knowledge. Or I must conform to "soft" interfaces that have no immediate enforcement to test against (think dumping files to a third party system). In my situation the specification is everything.

share|improve this answer
Since this is closed, going to reply here. I don't think that really necessarily works. Domain knowledge in many areas (financial software for example) is usually a prerequisite to making heads or tails of the spec. What a spec does is it gives you a document you can use as a shared reference between the programmers on the team. No more. No less. – Chris Travers Sep 8 '12 at 9:21

Not the answer you're looking for? Browse other questions tagged or ask your own question.