> Specs are a way of life where I work. I would hope that everyone would be good or learn to become good at writing useful precise specs.
I was honestly hoping this was a joke, but I don't think it was. By the time someone writes an accurate spec, the business need has already changed. Spec's don't work.
"The most important function of a spec is to design the program. Even if you are working on code all by yourself, and you write a spec solely for your own benefit, the act of writing the spec -- describing how the program works in minute detail -- will force you to actually design the program."
Sure, you'll still find out the design was wrong in some areas, and you'll have to change it. But at least you'll have a design to start from, as opposed to a hodgepodge of features carelessly tossed into the interface wherever the programmers found it most convenient to stick them, implemented in whatever way made the most sense to the programmers at the time.
> Since when did specs become immutable? Needs have changed? Patch the spec. It's faster than patching the software.
I don't understand how this can be faster. You patch the spec, then patch the software to match. I can't see how the spec could be patched faster. That is unless you patch the spec in isolation, prior to writing any code, which is a bigger mess. I've never, ever seen any group that can write a spec in isolation prior to writing code to demonstrate it, and have it come out well, its usually a disaster.
The idea is by having a spec, you're more likely to see where it needs to be patched upfront, before delivering poorly designed software to angry customers, so you spend less time re-working it later on.
> I've never, ever seen any group that can write a spec in isolation prior to writing code to demonstrate it, and have it come out well, its usually a disaster.
Can you elaborate? I'd be interested in hearing what they were building, who (in general terms) they were building it for, how they went about writing the specs, and what went wrong.
My experience has been completely different, and I'm curious as to why that is.
Edit: Of course you can't expect the customer to write the spec. Designing the software is your job. But that doesn't mean specs are broken; it just means asking your customers to write your specs for you is broken.
In my experience you never really understand a problem until you've implemented it. You can describe a problem and a solution in excruciating detail, but you'll never find every corner case. Sometimes (often?) those corner cases are really big deals.
Better to prototype and iterate. Software should be the spec.
Agreed. Version 1.0 is a glorified prototype anyway. Nothing about writing a spec prevents you from prototyping and iterating, though. These are not competing ideas.
Of course you won't get everything right in the first draft of the spec. You won't get everything right in the first release of your software either. That's not an excuse to stop trying.
Let's suppose you write a spec, then go on to write some code. For each design problem that makes you break from your original plans, one of two things is true:
(1) Someone noticed a problem while writing or reviewing the spec, and changed the design. You've saved a ton of time over implementing the wrong thing and then changing it later.
(2) You didn't notice the problem until implementation. It still takes just as long to fix as it would have if you hadn't bothered writing a spec first.
If #1 is common enough, writing the spec saves you time. At worst, #1 never happens and you're out the time it took to write the spec. But how long does that take? In my experience, it takes a lot less time to write a spec than to actually implement it.
There's a lot of potential upside and little potential downside.
I don't advocate Epic Design Up Front—at some point, it's time to stop planning and start doing. But I do advocate Some Design Up Front, as opposed to Let's Wing It And Hope For The Best.
> Software should be the spec.
Software is not a spec. It's written in computerspeak so only the programmers can read it, and sometimes they're not even completely sure what's going on. Without a spec, QA has nothing to test against, so you get into arguments about how things should work because there's no record of any decision on the matter. There's nothing to write documentation against, so the documentation ends up worthless. Sales and marketing make up all sorts of neat features you get to implement whether they make sense or not because they've already been sold, and you can't really say they should've known better because you never bothered to write down what they should know in the first place.
If all you have is code, you don't have a spec. Code is not a spec.
> My experience has been completely different, and I'm curious as to why that is.
The majority of people who request 'software' haven't a clue what they want, they can't possibly describe it, you can't possibly write a spec for it. See years of research regarding waterfall vs agile development as a reference.
Business software isn't about "what they want", it's about coming up with a solution to meet a business need. If the customer can't define what their business need is (the why of specs), then they have no reason to be in business.
It's not the job of the spec writer to define the business need, it's to take an existing need (after clearly defining it through consultation with the customer) and then defining the parameters of the software - inputs, outputs, business rules.
And it has absolutely nothing to do with agile vs. waterfall development. A well-written spec is crucial to ANY business software project.
We do agile development at my company (a 25 year old enterprise software company) and will not begin work until we have a well-defined spec. I continually reject spec docs if they don't have enough info or if I have questions about an aspect of it. It's your job as a developer to help the spec writer see what problems may crop up and define a solution for them.
I think you need to read Code Complete. It's absolutely mind-blowing the respect for specs you get after reading that book, even just chapter 3.
I find it interesting that I've gotten downvoted for this comment. Building an MVP and then iterating seems to be the modus operandi of the HN community. Building a detailed spec is the anti-thesis of this movement. How does this correlate?
I didn't down vote you, but my experience with writing specs has been positive.
Maybe you are talking about running your own start-up where it might not be successful yet? And you're trying to find your market fit? Then sure, maybe just writing new code and changing the product on a whim is what is best without writing up a spec.
Now consider a software consultancy with enterprise customers. The enterprise usually wants time and cost estimates, which usually means agreeing on precisely what you will be delivering in advance. You WANT to write a spec, to prevent scope creep and limit your liability, and they want you to tell them how long and how much (and a spec helps estimate those things). It's win-win.
Most enterprise customers can't wrap their CFO's head around true agile with iterations and open-ended times and costs. They want as much of a guarantee as you can give them for what/how long/how much.
Not saying one way is better or worse - but maybe it's a case of the right tool for the job?
Because the fact one model is working for the HN community doesn't mean that other models don't work but you made a very definite and sweeping statement.
We use specs because our customers tend to be somewhat staid and want certainty and predictability. By keeping chunks of functionality relatively compact (say 3 person months typically, then developed over a period of maybe 6 weeks) writing an accurate and useful spec is absolutely doable.
Doing that we'll usually be 95% (or more) right and any adjustments can be made in a small release a couple of weeks later.
The approach has elements of agile and iteration in it (small releases, the UAT and fix process is basically a short agile sprint) but specs are absolutely a working part of it. Could we do it another way if our clients would accept it? Sure? But do the specs work in the current process? Yes they do.
If you get your feedback on iterations in writing, you will probably get fewer self-contradictory or illegal, immoral, unethical, or unimplementable demands.
I was honestly hoping this was a joke, but I don't think it was. By the time someone writes an accurate spec, the business need has already changed. Spec's don't work.