Slashdot Mirror
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?"
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.
Step 1: Export those Word documents to HTML
Step 2: Place HTML documents on webserver, hang around on slashdot until deadline and claim all their requirements have been fulfilled.
Step 3: ???
Step 4: Fired!
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.
http://michaelsmith.id.au
This is something that I also struggle with, so I'm very interested in any tips 'n' tricks that others can supply. The only useful trick that I've found helpful in the past is to take an iterative approach to the documentation, repeatedly sending drafts to the interested parties and encouraging feedback. Often their problem is that they don't know what they want, only what they don't want - so starting to lay out some options before them helps them make decisions on what they would like to see. Start at a high level, and slowly drill down on the detail - making assumptions where necessary to keep the process moving, but always verifying those assumptions with the interested parties.
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.
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.
It's true I tell you, feller at work's next door neighbour read it in the paper.
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.
.NET has something similar.
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
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
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
I write a blog now, you should be afraid.
123. This is a major requirement.
123.1. This is a minor.
123.01A.1. Please refer to 782.5.1¾.1A.
123.5.1.A. This is a MAJOR requirement.
78.a7.A. A history should be kept for all items. Never should any item be permanently deleted.
342.8. Wullywuz must always be permanently deleted.
8 of 13 people found this answer helpful. Did you?
* 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!
Work smarter, not harder.
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?
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.
C - the footgun of programming languages
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.
We've found that writing User Stories 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.
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
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.
-- Patent no.123456: A way to personalize
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.
TCAP-Abort
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
Agile Estimating and Planning by Mike Cohn
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.
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. 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).
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.
"To hope's end I rode and to heart's breaking: Now for wrath, now for ruin and a red nightfall!"
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.
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.