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?"

he's right

Your boss is correct: it is your job to get accurate specs.

In my experience, the best way to get these is *not* asking people what they want or need (because they are usually not capable of putting that into words), but to observe how they do things right now, and determine which features they need (or which features would ease their workload) that way.

Re:he's right

Absolutely. Get your ass off your chair, walk over to the users, and talk to them about what they need. Then write yourself a detailed spec if you feel you need it. Then turn that spec into some paper-based mockups and walk the users through it. Then make any corrections needed. Then write the software.

And count your lucky stars that your company is incapable of writing proper specs - if they were, they would have outsourced your job to India or Brazil a long time ago.

Daniel

Re:he's right

Are there actually companies that write proper specs? I've only been doing IT for 19 years and I have yet to find any place where it actually happens. It's something I've always heard of, but never ran into anyone who had actually seen it happen. Generally, I've found the organizations least capable of writing specs to be the ones most likely to outsource, not the other way around. I think the idea is that if you don't know what you're doing, you may as well pay as little as possible since you already know you're going to fail. I agree with that philosophy, which is why I expect to be paid more for projects that people want to succeed. =)

The real goal is to ensure that the developers and users/customers are trying to address the same problem. The specs/requirements/design phases are just ways to document everything so that when it doesn't happen, someone can point to a document and said "this is what you said you wanted, pay us". It's a legal CYA. This is why it's more important to have these documents when the users and developers aren't part of the same small group of employees.

Re:he's right

but being informed on actuarial terms is not my business

Then you'd better have some damn good and damn accommodating domain experts.

An analyst's job is to understand the business rules and figure out how they can be sanely implemented in an IT solution. (Or, more importantly, when they can't.) And unfortunately, that sometimes means learning the jargon.

That's why my general (25-year) experience says that the best analysts are, first and formemost, generalists: capable of quickly absorbing the rudiments of any computable field of human endeavor. If you're doing the systems engineering for an accountancy, you'd better learn the fundamentals of accounting. Automating medical records? Learn medical recordkeeping. Weather forecasting? Heh. I could pass for a forecaster now, in casual conversation, because I've worked on weather data-gathering and forecasting systems so long.

Obviously, you are one of those quick-study generalists I spoke of, because of the breadth of (successful, I presume) systems you've helped implement.

That just leaves the problem of customers who don't actually know what they do, at least in enough clarity and specificity to implement as software. That's just a matter of patience and iteration. Prototyping can be helpful here, if you have time. Otherwise, I guess you just have to sigh and assume your first cut will be wrong.

And parent comment is right, too. MOD PARENT UP!

I agree with the parent comment. It's too big an intellectual challenge for most people to think about the details of software design. Users just want their software to work.

The correct approach is a very loving one. You try to discover what would make their work easiest, and make the software do everything software can do. Most jobs require that a person turn himself or herself partly into a robot. That's wrong. If a machine can do it, a machine should do it.

Programmers typically say to this, "I just want to be a programmer, not a sociologist." The real world requires every one of us to be a sociologist, or be out of touch with what's happening.

--
Is U.S. government violence a good in the world, or does violence just cause more violence?

Re:And parent comment is right, too. MOD PARENT UP

Domain knowledge is what makes you really valuable to a company. As suggested above, go and work with the users to figure it out, and then implement it. If anyone wonders what is taking you so long, be prepared by documenting exactly how you spent your time learning the procedures / formulas. That kind of documentation is useful come review / raise / bonus time. Seriously, it can take years to gain high levels of domain knowledge.

One example I can bring up from my past is designing industrial test equipment used for calibrating mechanical metering devices. I spent a month where I worked side by side with the people who would be using the equipment, 9 months developing prototypes (including all the hardware and software) and ended up with a product that cuts a 15 minute procedure down to 2. Again, I had to work with the users to see how they used the prototypes, and refine the hardware / software to real-life conditions. I even had to consult with a physics professor at the local university to help with some of the complex flow equations (physics is not my specialty, but I know enough to be dangerous... :-)

Could I have ever expected my users to develop detailed specs? No way - it's not one of their core competencies.

Re:an unrealistic ideal

I am by no mean a professional developer, however I develop a data analysis application that my collegues use in my lab (I hope to release it on Sourceforge soon). I do it not only for *my* data analysis, but also for other kinds of analyses, so I discuss "specs" from my collegues and implement them.

What I found is that when they are in front of the app, after a bit of usage they think "could you add feature X?" "how can I do Y?" and so on. I implement X and Y, and only then they ask "oh, you did Y? So why not Z?" etc. So the spec becomes dynamic, in the sense that only when they see a milestone accomplished new possibilities come to their (and my) mind. It's a climbing process. I don't know if it's the same also for pro developers.

Re:an unrealistic ideal

What I found is that when they are in front of the app, after a bit of usage they think "could you add feature X?" "how can I do Y?" and so on. I implement X and Y, and only then they ask "oh, you did Y? So why not Z?" etc. So the spec becomes dynamic, in the sense that only when they see a milestone accomplished new possibilities come to their (and my) mind. It's a climbing process. I don't know if it's the same also for pro developers.

If you are lucky enough to live and work in an environment that allows this, then it is, IMHO, the absolute best method for developing software. Now unfortunately, in much of the world, and especially at larger companies, very rigid software development practices are followed that make this sort of agile, iterative development difficult or impossible. I am lucky; I work at such a company,and work directly with a group of developers who use a very rigid, unflexible system; we don't see the product until it's been completed based on the spec - any iterative feedback I or my colleagues has is worthless, and would have to be done to fit into the next quarterly release cycle. Luckily, I also do my own development for some internal departments, and am given the freedom to work in a more agile manner.

Systems Engineering

Its called Systems Engineering and its a whole other profession. For a large, complex system like the ATC systems I work on syseng could easily account for 30% of your staff. Remember that getting the design right in the first place it the hardest part.

The only way I can think of the convince the "sales" people who apparently run your site is to create a really big stuff up and document it in advance to make them culpable. The problem is that they will probably just get rid of you when they respond.

You could try a kind of passive-agressive approach. Keep misunderstanding them. A bit like a monty python sketch. Don't go so far that they really get angry. Judge it so they come to their senses and start to write down exactly what they want.

Isn't there an old adage: The user got exactly what they asked for but not what they want.

I think you are screwed. Sorry. I have been in that situation before.

accurate specs

You draw a pentagram on the floor and place lit candles at each of the corners, then I'll dig up the old spell book. We should have this covered slightly after the first full moon.

Force them to say What, not How

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.

Impossible

What you think your job is, and what your actual job is are two quite different things. Traditional software 'methodology' is bunk and doesn't work - this is why you are confused.

You think it works like this:
- User knows what they want
- They write it down
- You...?
- Programmers implement it (probably wrongly)

If you consider your job more like an architect, then you will see the flow is really more like:

- Users think they know what they want (maybe)
- They can tell you what they DONT want
- You interpret their needs/desires in to a design and spec
- Programmers implement it (probably wrongly, but nothing is perfect)

If you think about what architects do for their clients, they figure out roughly what the client wants (house, building, garden, etc) and various parameters specified and unspecified in fuzzy things (building code, safety margins, design principles, aesthetics, etc). They then produce a number of different designs and design ideas to run past the client. Iterate a few times and then once they have sign off, build it.

If you were required to write some 300 page doc about the house you want, you'd be finding a new architect. Likewise, make life easy on your customers. I'm sure they have pre-existing documents and references regarding the accounting rules they need implemented (I assume you are familiar with accounting - if not, why the hell are you building it?!). But as for the UI and other software design features, most people just want something that (a) works (b) well (c) usable (d) does what they need. Meaning, don't ask for label or window placement.

If you have a RAD tool such as interface builder on OS X then you can create semi-functional mocks easily. I'm sure .NET has something similar.

Yes. This is hard.

obtaining accurate specs for these programs has become a huge challenge ... When I asked my boss (the head Sales manager) for specs, he responded saying that it was my responsibility to determine what was needed."

You're trolling, right? I hope so.

Yes, it is hard. Much harder than actually writing the code. Yes, it is your problem. Software Engineering is a profession. That's why you and I get paid the big (in theory) bucks ... to make hard things your problem. And solve that problem.

Without going into too much depth the process you have described (accurate specs, make software, test software against spec) is known as the waterfall model and is famously difficult to do for non-trivial projects. Can be done, don't get me wrong, but very very hard. Better, probably, would be to take an iterative approach: Take the word doc and bash together a prototype (RealBasic, Ruby on Rails, whatever); drop the prototype in front of the users and make notes as they say "nooo! not like that, it needs to do X, Y and Z"; feed back into the prototype and try again. Finally use this prototype as a "living" requirements document. The hard part is persuading the pointy haired types that that prototype is, in fact, not the completed piece of software. Yeah, good luck with that.

Not wishing to sound offensive but it sounds like your company needs to hire someone with more experience to act as a project manager. There's nothing wrong with writing code to spec (no matter how it's translated) and letting it be someone else's job to keep the project on track and ensure the users get what they want. And, in case you hadn't noticed, this job is hard f'kin work.

Dave

Become an analyst, and hire programmers

Become an analyst, and hire programmers. Then:

1. Don't make requirements anyway. Demand that they organize and create use cases and make them code the whole thing from there.
2. If that's not possible, let a web designing agency do screen layouts. Then demand they only talk to the agency. Web designers are easy to talk with; they don't bother with stupid details. Actually, they don't bother with anything but the screen layouts.
3. If you really must create requirements, create documents in PowerPoint. Make high-level, short and non-descriptive requirements. It's quite easy to design a system when you're in orbit instead of both feet on the ground.
4. If you haven't driven the project into the ground, create documents in Word. Word offers fantastic opportunities! Use track changes, nested tables, extremely large tables, bizarre macros, hidden notes/comments, etc.
5. Wait with submitting for review until you have a nice stack of documents. It's so much more economic (for you).
6. Do NOT refer to any other requirements. Just copy/paste and then make small changes.
7. Require prototypes in VB. Later, you can ask them what's taking them so long.
8. They want to MoSCoW your requirements. Conduct several meetings on hot, sweaty days and slowly but surely make them understand that each and every requirement is a must-have.
9. Make it difficult to let them get the latest requirement. Make it easy to get confused with old versions.
10. Make circular requirements. But don't make it too obvious: make a chain of, say, 10-20 requirements and only THEN refer back to the first one.
11. Make the versioning consistent with the 'Naked Gun' movies: 1, 2, 2-and-a-half, etc.
12. Never uniquely identify requirements! That way, it's too easy for analists and developers to refer and to maintain them.
13. Make sub-requirements that are sometimes numbered, sometimes with characters, and just for the hell of it, drop in some bullets, too! NEVER, EVER make it possible to sort the requirements in any way. Make sure to use the auto-numbering in Word, but sometimes just type them in yourself!
    
    123. This is a major requirement.
    
    123.1. This is a minor.
    
    123.01A.1. Please refer to 782.5.1¾.1A.
    
    
14. Hide major requirements in a very deep nesting:
    
    123.5.1.A. This is a MAJOR requirement.
15. Requirements should contradict each other, but not too obvious:
    
    78.a7.A. A history should be kept for all items. Never should any item be permanently deleted.
    
    ... skip a version and 300 pages ...
    
    342.8. Wullywuz must always be permanently deleted.
16. Make sure it's hard to reach you. Go live in another country. A different timezone is even better! Convince your boss to outsource to an offshore company, which is easy, since it's all the hype these days.
17. Include database tables in your requirements.
18. When the project has already started, make major changes. But first talk your boss into thinking that the system without that particular change is basically worthless.
19. ???
20. Profit!!!

Forget it

After working in the industry as a consultant for nearly 10 years, I can honestly say that none of the following has ever occurred:
* I've received a specification for a new project that accurately tells me what the program should do, and doesn't assume prior knowledge of the entire business;
* I've read the original specification for an existing project that matches the way it's actually been implemented;
* Management have believed me when I've informed them that either of these conditions are occurring and are preventing me from doing my job in a timely, effective fashion;

The lesson to be learned here is that there is no tried-and-true methodology that works across the board in IT, and thus there is no established framework for non IT people devising specifications for IT people. The problem is always going to be that each person in a business is so far down their own specializing holes that they forget how much people in other departments know or don't know. I liken it to teaching someone how to drive a car after you've driven for many years - after a while these things become ingrained in you, to the point you forget that your pupil doesn't know to hit the clutch before changing gears. CRUNCH!

Build a prototype

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 :)

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

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??

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

Face it. You'll never get decent requirements

It's a fact of life. Deal with it.

IMHO the way to deal with it is to accept it and make it part of your process. Since you're talking about in-house development and small to medium sized projects I'll recommend an agile, itterative method. Make a small incremantal release every other week and get your requirements from the user feed-back.

At the end of the day, users are unable to express what they what they want. They only knows that they have a problem situation and that they want a piece of software that makes all their problems go away.

Story Based Development and Agile

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.

Requirements Solicitation

Your problem is not unique. I attend an Extreme Programming workshop near where I live and a guy by the name of Richard Sheridan came to do a presentation on his companies technique called High Tech Anthropology [menloinnovations.com]. It was a great presentation and it is something you might try. Basically, you camp out in the users "Den" and observe them, taking notes and trying to understand how they work, what buttons they push, which user interfaces frustrate them, which things they like, etc. You then take this back and use it to publish your requirements specs. Some XP enthusiasts talk about bringing the customer in and having them work with them team, but Richard Sheridan makes a great point, that this can sometime lead to the users becoming more like engineers rather than the other way around (like the book The Inmates Are Running The Asylum). [uidesign.net]