Getting Accurate Specifications for Software?

spiffcow asks: "I design internal software for users that are largely computer-illiterate, and obtaining accurate specs for these programs has become a huge challenge. In the most recent instance, I asked for detailed specs on what an accounting program should do (i.e. accounting rules, calculation methods, and so forth), and received a Word document mock-up of an input screen, complete with useless stickers. This seems to be the norm around here. When I asked my boss (the head Sales manager) for specs, he responded saying that it was my responsibility to determine what was needed. How do I convey to the users that, in order to develop the software they want, I need detailed, accurate specs?"

Force them to say What, not How

[Bloke down the pub]

I try to get them to tell me how they would do it with a pencil and paper. They won't anwser the question as asked, of course. They'll say "I need some trancaction where I can put..." or "there needs to be some file where..."[1] - at this point you interrupt and ask them, again, how they would do it with pencil and paper. Eventually, you'll get to the answer. Then you, the developer/analyst, should be able to work out how to do it.

This forces them to concentrate on the what, not the how. You'd hope people would have the ability to intellectually grok the difference, without such a trick. You'd be disappointed.

[1] To them, file/screen/transaction/table/program are all synonyms. Never, ever, trust their terminology.

Build a prototype

[Lonewolf666]

In my experience, very few users are capable of creating a high-quality spec out of thin air. But when they get to play with a prototype, they will usually find out what they really wanted but are missing in the prototype ;-)

Be prepared to go through a few iterations, AND you might have to say "no" at some point because once the prototype - feedback - prototype cycle is started, requests for new features will keep pouring in.

If the above fails (some users will say they dislike the program but cannot tell you what they would like instead), your project is probably doomed. I've seen that happen before.

Haha.. welcome to the real world :)

[Johnno74]

This is typical, get used to it - or get a job where this stuff is left to specialists, business analysts.

Although I beleive you should go through the pain of requirements gathering at least once, it will make you a better developer.

I reccommend workshops. Get some users (and preferably also a manager or team leader who can give a different perspective) in a quiet room with a whiteboard for two or three hours at a time, and get them to walk you through the process. Draw diagrams, get them to explain things. Getting what they actually want out of them can be like pulling teeth. They will assume you understand their problems... assume nothing.

Make sure you do a thourough job, and get them to sign off on the requirements documentation you come up with in the end. If you don't and then end up building something that doesn't meet their needs then its difficult and expensive to change, and you will get the blame.

User stories

[dwerg]

We've found that writing User Stories [extremeprogramming.org] together with the 'client' is the only sensible way to gather requirements. Make sure you develop in short iterations, that way people can change their mind about the software and you don't loose a lot of time.

Maybe try a Scrum/Agile approach??

[ivano]

Scrum/Agile approach might be what you need since the feedback cycles force your client (the product owner) to think about what you misunderstood and what the product should become.

I am still surprised that people actually believe that you can have a specification written before even a line of code of written. No one is that smart and thoughtful. You need to break down what needs to be into big chunks and get your product owner to prioritize. What I like about Scrum is that it brings all the shit that usually happens at the end of a product cycle to the front of the product cycle. It forces the product owner to think about what they really need and what they expect (i.e. all the discussions about what the definition of "done" is). The hardest thing about Scrum for developers is for them to underachieve in deliverables. We've been spending all our dot.com boom period saying yes to everything without thinking about the consequences.

So my advice, whether or not you want to use Scrum, is to have tight feedback loops. Plan weekly demos (Scrum prefers monthly) of what you have done given the specs you've received. If there are disagreements you can then ask what they had in mind instead (which leads nicely to a discussion about what they perceive "done" means).

But all good methodologies have one thing in common: the product owner needs to work fucken hard too. It can't just be "here you go, I'll see you in 3 months time." Pretty much all methodologies fail when the product owner can't see why they need to work so hard ("prioritize my list of tasks?", "we need to free up these resources?", "can't the project manager do this?" etc etc) my 2 cents worth

Story Based Development and Agile

[JavaSavant]

I've found in the domain I work in (medicine) that story-driven projects tends to work pretty well, both in the way that estimation can be achieved and the degree of cohesiveness with which the "specs" or stories come together.

1. Identify each potential user of the piece of software;
2. Use a sample size of that group (e.g. an auto mechanic, auto body specialist, etc.) or proxies for those users, and given the direction of the project (workshop management tool, per se), solicit stories for development. A story should be short and describe a measurable unit of work from the users perspective (e.g. As a mechanic, I must be able to find a wrench in my toolbox.) Define any constraints (The mechanic may not search through the toolboxes of other mechanics) and acceptance tests the user can refer to to see that the story is complete (Any known wrench in my toolbox should be retrievable).

This approach allows you to avoid the technology and focus on the true business requirements. From this process, you can then size each story, scope the project based on features desired or a given deadline, and then things proceed fairly naturally. This has worked very well for me with Agile and working with small iterations so the users can see the manifestation of the ideas that produced the stories, and provide feedback so that you can add additional stories, remove ones that are no longer valid, and above all else - demonstrate progress.

Some good books on the subject:

User Stories Applied by Mike Cohn [amazon.com]
Agile Estimating and Planning by Mike Cohn [amazon.com]

Single author (no, he's not a friend), but both books that have been fantastic for me in terms of taking a fairly unmanaged project group and making it a much less squeaky wheel within my department.

Re:Force them to say What, not How

[cpuffer_hammer]

Right on, I like to say pen, note cards, a calculator, and maybe a clock. I then observe the process. Only then do I write an initial specification. I take that back to the customer for their review. If they have questions I determine if the question is about the specification, the process, or a lack of understanding. Then we make corrections and improvements.

I also ask questions to determine if the customer understands the specification and the process it describes.

The customer then has to agree to the specification.

Then work can start on the code. If during the process there needs to be a change, if I or the customer finds a problem or wants a change or feels money can be saved if something is done a different way, this process is repeated to create a change order.

As to questions, I always try to ask questions that do not have yes/no answers. For example (If I was working for a rare coin shop) when a new coin is bought by the your coin shop what happens to it next? What should happen to it? Or after the specification has been written, what will you do with a new coin based on this specification?

Yes, you may even have to help them change practices and policies. If you make this a value added, sell it as a additional benefit of automation or reautomation. (Rare coins shop again) when you add the new coin to the inventory right away the system will check it against the "customer coins wanted list" and you may be able to flip it (pun intended) to a customer who wants it.

There will be more than one contract: your employment contract, the project specification, change orders, and others. Don't skip the documentation.

Re:an unrealistic ideal

[PhilipMckrack]

In my experience this has always been the case. Some people are blessed with the ability to take what is on paper and visualize how it will function in reality but I don't work with anyone like that. No matter how much I drill down specs on paper and work things out, once development starts there are always changes. The best you can do is roll with it and develop the product they ultimately want. From the start write software that is easy to modify. Lucky for us, the client that usually has the most changes for me also pays us by the hour so it works to our benefit.