Slashdot Log In
Getting Accurate Specifications for Software?
Posted by
Cliff
on Wed Mar 07, 2007 06:30 AM
from the needed-before-a-single-line-of-code-is-written dept.
from the needed-before-a-single-line-of-code-is-written dept.
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?"
This discussion has been archived.
No new comments can be posted.
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
Full
Abbreviated
Hidden
Loading... please wait.
he's right (Score:5, Insightful)
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 (Score:5, Insightful)
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
Parent
Re:he's right (Score:4, Interesting)
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.
Parent
And parent comment is right, too. MOD PARENT UP! (Score:5, Insightful)
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?
Parent
Re:And parent comment is right, too. MOD PARENT UP (Score:5, Insightful)
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.
Parent
Re:he's right (Score:5, Insightful)
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.
Parent
Systems Engineering (Score:5, Insightful)
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.
Re: (Score:3, Insightful)
No, it's not necessarily your fault; however, programmers should become familiar with at least one area i
accurate specs (Score:4, Funny)
Force them to say What, not How (Score:5, Informative)
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.
Re: (Score:3, Informative)
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 spe
Impossible (Score:5, Interesting)
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
Yes. This is hard. (Score:3, Interesting)
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
Re: (Score:3, Interesting)
You even mention him
Become an analyst, and hire programmers (Score:5, Funny)
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.
Forget it (Score:4, Insightful)
* 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 (Score:3, Informative)
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 :) (Score:3, Informative)
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 (Score:4, Informative)
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?? (Score:3, Informative)
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 (Score:3, Insightful)
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 (Score:3, Informative)
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 (Score:3, Interesting)
Re:an unrealistic ideal (Score:5, Insightful)
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.
Parent
Re:an unrealistic ideal (Score:5, Interesting)
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.
Parent