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.
This is the kind of problem I always run into, websites, databases, you name it.
It would be great to be given a comprehensive and accurate spec for development, but in my experience it just doesn't happen! Maybe if your working for some large development company - where it is someone else's job to develop such a specification, you may be lucky enough to experience such bliss, but elsewhere you can just forget it.
More and more I am learning that it is just easier to do everything as best you can, using your own judgement, doing all the information gathering yourself. If what you do is not what is wanted, then just make the changes. It might suck, but that's how it goes.
Ross Kendall Web Consultant and Developer (UK) - Drupal and Open Source Solutions
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
Why don't you have the users write the program as well? Your boss is right. Do your job. You should be fired.
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.
While it's nice if the customer knows exactly what they want, the only people who can really do this well are usually software engineers. A lot of the time, working out specs takes me as long as writing the software.
People really really don't understand software. It's a form of magic to them. You need to find out what the inputs and outputs are, what the behaviour should be in specific cases, and gradually refine a spec from that.
This sort of problem has caused a lot of expensive IT white elephants. Some of the more successful companies seem to have an intermediary to operate as a translation layer between the developers and the customers. Or to put it into non programmer terminology, to translate the requirements into geek.
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?
Start getting the head manager to define a business case. Then with that define a vision for the project in cooperation with all participants. Scope your vision with the help from the input from the users.
Make sure you have involvement from management, which is critical for success.
Define all roles: Who is the "customer" and/or stakeholder, who will test your software for you (you can't do that yourself wi) who will be responsible for managing requirements and who will develop.
You actually already have the step to iterate trough steps for a solid projectplan.
Make af mockup / prototype and show it to the project members (users managers etc.) And iterate until you have a working specificatio
If you don't follow these important steps, you are about to be part of the high statistics of doomed software project without a clear scope and stakeholder involvement.
In order to form an immaculate member of a flock of sheep one must, above all, be a sheep.
I design internal software for users that are largely computer-illiterate ...and yet you expect these people to write high quality accurate software specs. Why?
Parent is exactly right, it _is_ your job. But even then, if you need specs, they are for your own use. There is no point writing thick specification documents for the users as even if they are accurate, they will not be read/understood by the people you are writing the software for.
So prototype. Start off with a paper based mock-up as sibling poster suggests, and follow up with a complete click through GUI before you write any code. Run through this with them and make sure it is what they need before you actually write the software.
Try this one:
http://www.oreilly.com/catalog/hfobjects/
Fairly simple, fun to read and far more useful than it appears at first sight.
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
Its hard when you don't have enough scale to do things properly. Small is OK. You can work on your own, specify it code it and sell it. Big is good. You can have a pipeline from customer requirements to specification to development to integration and validation. But in the middle is a zone where steps get compressed and people have to improvise. I have been there and its not good.
http://michaelsmith.id.au
If you want "accurate" specifications, write them yourself. Interview the users, find out what they think they want, what they actually do and then determine what they actually need. Then you write up a draft specification, present it to them and get their feedback.
Developing specifications is often harder than writing the code. You need to engage in a dialogue with your users to really elicit the requirements for the systems. Requirements gathering and analysis are tasks that shouldn't be left to the users, especially computer-illiterate ones, you need to do the work to create the specifications.
Your direct report is to the sales manager and you are a programmer?
Unless you are contracting on a very attractive rate then personally I'd be looking for something else.
You are going to be in a position where you will get all the blame when things go wrong, be given riduclous deadlines with the assumption that just by pressuring you harder they can get better software faster, no assistance from your manager, vague and contradictory statements of requirements from your users and since they won't be earning comission while they sit down with you for you to slowly guide them through stating what they actually need they will probably resist doing it.
Oh and while you get all the blame, you probably won't get any of the credit.
Frankly there is no way I would want to be in that position as an employee - if I'm working as an employee I either want to be the technical/project manager or working under a competant one, with the authority to get the resources needed and the sign offs in advance.
Of course if I am contracting on a daily rate then as long as they are offering enough I'd put up with most things and do my best to deliver something useful though I would expect it to be an uphill battle.
$_="Slashdotter";$syn="OTT";s;..;;;sub _{print shift||$_};s!ash!Perl !;s=$syn=ack=i;tr+LLEd+BLAH+;_"Just Another ";_
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.
Do their jobs for a while to find out what is actually needed as opposed to what they think they want. Sales staff people usually have little idea about what's possible.
Mock-up a few screens and talk with your temporary coworkers to see if they think what you suggest would be useful.
Avoid the bosses, they usually have little idea about the finer details of what their staff actually do.
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
These seem appropriate
n g.jpg
r e-project.jpg
http://www.monolithic.com/pres/tree_swing/treeswi
http://www.jroller.com/resources/behrangsa/softwa
$_="Slashdotter";$syn="OTT";s;..;;;sub _{print shift||$_};s!ash!Perl !;s=$syn=ack=i;tr+LLEd+BLAH+;_"Just Another ";_
First off, is the question of who needs to produce the spec. The answer, sadly, is 'you' - if you're developing it, you need to produce a 'final spec' within the context of what you're able to produce.
However that's not the whole story by any means. You're also correct in saying you can't really make decisions on what stuff should do, and how and why. That's the really hard part. It requires a collective effort, between you and your users.
Unfortunately most of your users are also going to be wanting things that 'just work' so you'll possibly need to arrange with various managers that you _need_ your time, and theirs to get an accurate specification and requirements together.
Now, most will co-operate. You'll be able to talk to your users, and get them to take you through the aforementioned word document with sticky lables, and ask exactly what they mean.
Remember - your users don't understand 'technospeak'. Even simple stuff like what kind of button - they may not appreciate the difference between a radio button, and a drop down list.
Unfortunately, if you take away what they said they wanted, and do it, you'll be wrong. Which is why you need to draw up a 'spec document'. It's dull and long winded I'm afraid, but not nearly so bad as having to write and rewrite the thing you're working on, because the communications between you and your users isn't as effective as it could be.
Ask them to explain it. If there's something that exists already, arrange to watch them doing it, or better yet, use it yourself for a day or two. Draw up your document with what you 'think' they mean, in as clear a manner as possible. And then ask them to look at it, and feed back on correctness or amendments.
You can't do a spec without their input, but at the end of the day it's you that needs to do the spec - this is both because most end users are not IT savvy enough to put together something that you can use to code from, and because that way you have some control over nearly impossible features you sometimes get asked for.
Oh, and get manager 'buy in' on you doing these things. If you need to speak to the users for a long time to get it right, don't just assume they'll be able to put whatever their 'real' job is on hold whilst they do. At best, that annoys them, at worst you'll get told they 'don't have time' and you'll be stuck at a dead end.
Have the end user organization be responsible for the User's Guide. In THE Guide, they show all the screen mock ups, with details as to how each element works, including calculations. Warn them that Accounting uses a special kind of math that only Accountants are taught and ask for a copy of Quickbooks to validate your calculations for specific scenarios that the users create.
Unfortunately, Use Cases and other UML techniques are lost on most users. I've been in many, many arguments about "that isn't what a meant" with users. Stick to your guns - "that is what I heard" and please show me where you told use differently "in writing."
If could be that you are in a no win situation. Update your resume, there are better jobs available.
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 find that customers like this are far better at telling you want they don't want, rather than what they do want. This can be very unhelpful as it can lead to your not knowing that what you're making is incorrect until it's actually finished.
;) This spec will almost certainly be totally unacceptable, but you should then ask the customer to approve it.
;)
The best approach is for you to spec out the system as best you can yourself, using what little input you do have (perhaps including some glaring errors on purpose
Generally you'll get a whole lot of input about what's wrong with this system that you 'almost' built. Hopefully you can then work from that.
Of course, depending on just how unreasonable they really are they might get rid of you just because your spec was so wrong
Some degree of education of the users may be in order, in your case. You need to understand their language and they need to understand yours.
but in many (possibly most) environments, this idea that a large system can be specified entirely upfront is myth. Business priorities change, problem areas are uncovered, understanding of what the system needs to do is improved (on both the programmer and user side). You may well be in such a fluid a poorly-specified situation.
Waterfall methodologies are usually broken. Try an agile approach such as scrum instead.
My Karma: ran over your Dogma
StrawberryFrog
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).
Full and Accurate specification, i don't think it can be full and accurate, in my experience it either has everything in it but it is not what the user wants or it has what the user wants but not everything is in it. Should create some programming law about that.
Don't discount the users opinions, but it is a good software designers job to ask questions and offer suggestions to get around the users weird ideas. But observe them, if you understand the process they are trying to do then you can offer alternatives which might help them, and make their lives easier... They will love you for it, then curse the programmers who can't work to your perfect software.
How do I convey to the users that, in order to develop the software they want, I need detailed, accurate specs?
It's your task as a developer to get the specs you need and to communicate with users in a way that they can understand. Furthermore, it's never as simple as simply requesting specs from them; usually, you have to build prototypes, collect detailed feedback, and do many iterations of that. Throwing away most of your work over and over again because it doesn't do what users want is part of the job.
I'd say that 90% of software development is figuring out what needs to be done--getting the specs. So, do your job.
The way I have to work is that I produce a spec from client meetings and discussions, which then gets sent off for approval. The client knows the the approvals process is important, because anything that deviates from the spec (when it's down to them getting it wrong, not us) will cost them extra.
We value the spec because it's what we work to, the client values the spec because it's their bottom line. As a result, we work together to ensure the spec is right before we start.
You are a programmer / app developer, who reports to a Sales Manager, and have to write an Accounting app? But the users can't explain what they do? Easy - look for another job. More seriously, plenty of good advice has been already given. My 2c. 1. Map out the process flow wih the users. NOT what they THINK happens, but what really DOES. Also at this time collect key information such as volumes, number of users... 2. Determine how it could be improved, even without some kind of IT support. 3. Then, map out how a system could help (your job here is to make users aware of possibilites & constraints) Keep it as SIMPLE as possible. Go for the minimum functionality required to do the job. 4. Prototype your work & data flow, then you can work out your DB structure, core logic and I/O. 5. Storyboard it, with dummy screens & reports (suggest you do not waste time writing any code yet). 6. Once everybody has signed off, you can get to work. Keep the users involved regularly, (once per week). Keep asking &checking "is this OK"? But avoid scope & function creep. Finally, dont forget to select tools & architectures that make it easy to add function later, & for easy end-user reporting. The ones you select will depend on your experience & environment, of course...
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.
You're an idiot. Different skillset doesn't mean that somebody is necessarily stupid. Being able to sell the product that you're making is a very important skill... it's what actually puts food in your stomach. Somebody in sales may not be able to write code, but then, how good are you at dealing with the customers? Most of the engineers I know have really shitty social skills, and their sale rate would be a lot less than somebody who specializes in the task.... You might have the satisfaction of saying that you never had to deal with a salesman who didn't grok what you're actually capable of with the code, but at what cost?
If you have a communication problem with sales and it's causing unrealistic expectations and project goals, then the problem is in part your fault: you're not communicating with them effectively enough to pass the message that something's not possible. Personally, I've never had any problems dealing with sales: most of them get pissy when you say "no. that's impossible." but understand when you say "no, that would be extremely difficult, here's why. it's possible, but not within our current timetable."
If you believe everything you read, you'd better not read. - Japanese proverb
What you need to do is interact, one-on-one, with (a) the people putting information in, and (b) the people taking information out. If it's the same people, so much the better. But don't go into a stuffy room with a whiteboard -- not yet. Find key users (not managers!) and start by asking them two simple questions: (1) What do you do all day? (2) Can you show me? Every time you see something, discuss it with them until you understand it well, then write it down, right then right there. Ask them what's tedious. Ask them what's important and why. Ask them what happens if a particular step is omitted.
Take all this back to your own desk and start doing mockups. Take these back to the users for round two, complete with observations like "I noticed that you spend a lot of time matching the numbers on this sheet of paper to the numbers on this other one. It looks like we could merge them together right here." Be prepared to have your design ripped to shreds, but have
Failing that, call your grandma on the phone and tell her that the users are writing "terrorist accounting software." The CIA, who is tapping your phone, will abduct them and fly them to one of those countries Amnesty International is always talking about, where a Haliburton sub-contractor will gather requirements for you. Six weeks later a New York Times reporter will discover the users wandering a dusty third-world street. The reporter will piece together the whole story into a five-part series that eventually wins the Pulitzer Prize. Part three of the series will be all the sordid details of the software, obtained from an anonymous whistle-blower at the Justice Department. The following spring a book called The Best Reporting of 2007 will be available in paperback, peaking at #237 on Amazon. Buy the book along with Karl Weigers's excellent Software Requirements, Second Edition so that you'll qualify for Super Savers Free Shipping. Using the two together you'll be on your way to award-winning software, but after the awards ceremony, don't accept offers of free rides in unmarked vans, even if they say they have a Wii console in there.
This is not my sandwich.
Type 1 : insists that the user provide them with specifications for their system. They sit waiting for this document and when it eventually arrives they ignore it and the users and write something that doesn't meet the requirements anyway. Eventually these software developers either get put in a corner and ignored or sacked. They usually moan that users are a pain.
Type 2 : they discuss the requirements with the users and draw up a spec themselves. In constant dialog with the users they convert the requirements into code that implements a system that approximates to what is required. Its never perfect but it does the job. These software developers get respect from their user community and get promotion. These software developers while finding users a challenge to deal with, actually like helping them.
My advice is to do what your boss suggests and write the spec yourself and talk to the users.
When I interview software developers I have some major turn offs. The first is developers who complain that users are a pain and those that complain that the system failed because there was no spec or it was badly written. As an employer you need software developers who are pro-active and talk to their user community. Ones who wait passively for users to make up their mind are not worth hiring.
1) FIRST: DO NOT INTERVIEW MANAGERS. Interview end users. I can't remember all the times I've seen software that was spec'd by managers who allegedly knew it all, and the end users did everything they could to not use it, or get around it, because it was so hostile, and did *not* work they way that they needed it to.
2) Sit them down, one by one, in a chair, and bring out the rubber light bulbs, and bare hoses, and beat them around the head and shoulders until you find out what it is they actually need as a result, *not* how it should be done. They used to teach one design method called HIPO charts: get what comes in, and what they need to come out, from them. *YOU* are the software professional; how you get from a to b is *your* job.
Lest you think I exaggerate in 2), there was a time, at one job, I had a chemist come in and ask me to convert the (dBase) files he had on a disk to ASCII, so that he could massage the data to create a report. I brought them up in dBase, then beat him about the head and shoulders, until he admitted what it was he was trying to produce. Then I asked him how long it would take, if I converted it, and he told me two or three days. I looked at him, and asked if he'd like the same report in two or three *hours*. The tables were perfect. All I had to do was create the query, and format the output.
So, remember, you get the rules, but *you* have to figure out how to get from here to there.
mark
yea, nothing new here, the other replies seem to have summed up every way i know of dealing with this problem, but i will say, be thankful you never received such mock-up input screens via fax machine, that can be extremely painful.
How are you still employed? The users aren't your enemy, they're your customer. How would like it if you went to a tax accountant and he treated you this way just because you hadn't done all of the hard work before you brought your information to him?
Ignore this poster. He's probably "between jobs" right now.
If you really want detailed specs from your users then create some forms for them to fill out with specific questions about the aspects you are unsure they need included (like calculations to be performed at certain steps). Better yet, if you give them a proposed workflow diagram with adequate explanation of each step and let them crtitque it you'll end up with a much better idea of what they're asking for. You'll get the added benefit of getting the user to start thinking about how things work outside of their own little specialty. You may learn something in the bargain as well.
I would have to agree with a previous poster that anyone who expects to only have to do coding after someone else has done the spec gathering should not be surprised when they get notice that their job has been moved to Mumbai.
"How do I convey to the users that, in order to develop the software they want, I need detailed, accurate specs?"
You're absolutely right that it would be a lot easier for you to do it right the first time, if you were handed detailed specs.
But very, very few companies are willing to pay the expense of getting the specs so correct that developers will build it right the first time.
So, what do you do? You iterate. A lot. You try to identify the hard parts, and try to get them as clear as you can. If your users could describe the behavior they wanted exactly, they would just code it.
That's just what a software engineer does - turns desired behavior into a specification so clear that a moron could do it. The computer is supposed to be the moron, not you. Your users are going to give you specifications that are not as clear as you would like, and you are supposed to turn them into specifications that are much more clear (i.e. source code.) That is literally your "value add," and it's why you have a job.
Education is the silver bullet.
It doesn't matter whether a saleperson has an IQ of 40 or likes wearing polka dot everything. If the sales targets are exceeded and the money is pouring in[1], anything short of significantly criminal is usually forgiven by management.
;) ).
It is actually much easier to measure what Sales does, and if a salesperson doesn't meet targets, well it's usually bye bye time. Sometimes it's not even their fault - it could be they are made to sell a crap product (produced by crappy developers
In contrast sysadmins could be reading slashdot all day AND that could be a sign of them doing their job properly - nothing goes down, and anything that has problems doesn't fail immediately warnings get sent in advance, and hardware/software fixes are scheduled.
[1] The salesperson is selling to people who actually pay. There's a very significant and important difference between people ordering your stuff, taking "delivery", saying they will pay, vs them actually paying.
Never give users a choice. They invariable choose the wrong one.
Let me guess, you never did a degree, or took any Software Engineering classes. Only programming.
Working out the specs is one of the hardest processes you will have to face.
Meetings, meetings and more meetings with the customer (the person who you are designing the app for), asking loads of questions.
My first exposure to the rewrite of this code was in a large meeting where all the bigwigs were present for a presentation by a consultant who rewrote the PC based software into an AS/400 based system like the rest of our software. After the presentation, the scheduler, who was the main user of the software, cut down the consultant personally and told him his software was crap! Soon after this, I was brought in to be a mediator between the scheduler and the consultant. They hated each other so much that they didn't even meet together anymore. All communication went through me. They didn't even refer to the other person by name, rather using eupemisms like "your friend".
Here is the kick - the consultant told me when he started on this, he sat with the scheduler for 2 hours and then the scheduler got all huffy and said "I don't have time for this!!! Just write something and if we don't like it we can change it!"
This was SO different from the job I had prior to that where most users were extremely computer literate and helpful with writing specs. They considered the IT department to be a competetive advantage and not just a necessary evil.
You know, for a salesman, there were remarkably few spelling errors in there. And I'm pretty sure you didn't write in crayon. You must be the manager of the sales department!
For many years the IT department would always suggest getting one of the magic buttons to the delight of all.
Why? If it takes you more than a few months capture requirements for design the business rules will change. You really, really need to have respect for and make the best use possible of the people in 'the trenches'. Don't rely on managers or analysts, they often don't know how work *really* gets done. If there is more than one site, interview people at *all* sites. Different sites often have different needs or business processes.
Small modules allow 'proto-typing' and feedback. This is a good way to discover hidden business rules.
If a legacy system exists, reverse engineer it and see what works and what doesn't. In fact, if you reverse engineer the legacy system and find it works well *do not* throw it away. Instead try to find a way to enhance it. Old does not mean useless, it may just need a better UI.
Be humble, because you are ignorant.
putting the 'B' in LGBTQ+
Depending on the functionality you are trying to implement, this can be a hard problem. This has been addressed seriously in the AI and expert systems arena, where attempting to reproduce processes performed by an expert in some domain or endeavor can be very challenging.
A number of techniques have been developed to address this problem of acquiring the proper knowledge of a domain expert. These include things like watching people do the task while thinking out loud and analyzing their actions, as well as structured and less structured interview techniques.
Your problem may not be as detailed or complex as an expert systems implementation, but the issue of acqquiring good requirements is universal, and if you can't get it specified at requirements time, then you need to get it interactively from people that understand the problem.
Look at the literature in the area of "Knowledge Acquisition Techniques" for more information.
In an effort to have some body text, I'll just ask one question:
Is your task accomplished by simply using off the shelf software?
OK, and one comment framed as a question:
Does anyone believe that you could write reliable accounting software without intimate knowledge of accounting rules?
"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. "
Good thing someone wrote an article about it. The reactions are a hoot though.
While it's useful to generate a prototype that your customers can respond to, remember that they will think it's real. So if it seems to work, you may be moved on to another task and leave an inefficient, unsupportable prototype in place as "the real thing". That can be very bad. Might be good to add lots of artificial delays in the prototype. Then you can keep explaining, "this is just a mockup, powered by squirrels running on treadmills; when you like what you see, we'll re-write the whole thing for speed."
I agree with those who are saying, effectively, that software development is an interactive service. If you want to code no-ops to the hard metal based on rigorous specs, you have to get a job in aeronautic or space navigation software. Anything else is developed impulsively based on customer whims, and you have to learn to enjoy that process.
I was brought in on a large project for a major moving company (you would recognize the trucks on the interstate) where performance problems were killing the business. The shipping industry is very complicated, and the rules and regulations required by the states and by the federal government easily fill several inches of books stacked up. How to codify all those requirements? Anyway, the end-users were seeing such bad response time that they had to add additional shifts in the off-periods to be able to get all their work done. Since it was a very complicated multi-tier environment (db, application servers, citrix, WANs, etc.) I thought I'd sit with the users to see what they were seeing. As the user went through the process of inputting a form from a piece of paper that was filled out by an agent at the customer's home, I was astounded at one point when the user opened up her drawer and pulled out a slide-rule like device that she then did a calculation on just to type it into an input field! Whoever had done the systems analysis of this application had done a really poor job! That really made an impression on me.
(The performance problem was due to a DBA insisting that he didn't need to pin the SGA of the database in memory).
Accounting rules do not follow the logic you have been using as a programmer, especially under a full moon during Daylight Savings Time in an presidential election year(Bad Joke).
Find an accountant you can easily discuss what others tell you. Let him discuss and work with the other accountants about discrepancies. You should concentrate on the product!
The only thing new in this world is the history that you don't know.[Harry Truman]
As suggested above, go and work with the users to figure it out, and then implement it.
I take that a step further - don't just go work with the users. Take some time to do the users' work. This is the absolute best way to get an understanding of their workflow - observing is good and also needs to be done, but when you sit down and do all the tasks yourself it becomes much easier to see which parts of their job are annoying, which parts can be sped up, etc.
At my last job they actually had me doing production work with the people I was designing software for a large portion of the time. This was huge, because it meant that on top of getting a better understanding of how the software I was assigned to work on should behave, I was also able to see spots where new software would be useful and began initiating projects on my own.
Having had that experience, I'm convinced it's the only way to design software. Otherwise it's a blind men and the elephant problem. People who don't know much about software development can't really provide a decent spec because they probably don't know a thing about software design. People who only hack on code can't provide a decent spec because they only have the a foggy, secondhand understanding of the problem domain. Users and programmers getting together for meetings is an improvement, but only a marginal one because there isn't a whole lot of overlap among their knowledge sets, which is a huge barrier to communication.
Congratulations, grasshopper. You are on the path to enlightenment.
You have to immediately forget whatever you were told about specifications. The real world doesn't work that way, where you get elegant descriptions of exact useful functionality. You're either going to get 100 page documents with way too much detail and a laundry list of features that won't really get used, or what you have right now -- which is, basically, nada.
The key to fixing this is iterative development. You have to give people something to react to -- then you'll draw out their real needs. Start small, be prepared to throw a few false starts away entirely, and you can build up from there. You don't need the full eXtreme Programming bit of having a full-time customer advocate and specific two-week/three-week/whatever iterations, but those concepts are good ones to model your process on.
Try reading the Creating Passionate Users blog for suggestions on how to get people actually interested in your project. Once you do that, you'll get the feedback you need, and as you deliver on those suggestions, you'll build confidence from them that will give you the carte blanche you need to start dictating the evolution of this project on your own. Once you're "the goto guy" on "The Project", you're in the sweet spot and basically can't lose.
It's a strange world -- let's keep it that way
The notion that one person can collect (useful) end-user information and then implement it technically is analogous to asking the same person to design and then build your house. It's possible, but unlikely to be successful for larger projects.
You need someone who is trained in collecting the user behavior data, understanding what that means, and using that to guide the design (from a user standpoint) of the end product. They will gather information by interviewing and observing the users. This may include asking them what they want, asking them why they want it (what are the actual goals, not just features), observing the work they do, and understanding the greater context in which they do their work. Once they have an understanding of the needs, they will probably create many generations of cheap (perhaps on paper) prototypes that they can use to quickly acquire and integrate user feedback. Once that process has mostly defined the product (or aspects of a product) it can be turned over to you to figure out the technical implementation. (Of course the earlier on in the process that you are involved the more input you'll have on the final design.)
People who fill that role (or subsets of it) are commonly referred to as interaction designers, user experience architects, information architects, usability specialists, etc. They should be trained in accurate data collection, cognitive psychology, interface design, and a number of related skills. "Web Designers" frequently have a background in graphic design and don't have the rest of the training to make them the right person for this role. Accept no substitutes.
For more information on what this role is about, check out sites like Cooper, Boxes and Arrows, and OK-Cancel.
Good luck!
I use Compendium and Freemind as part of the software development process.
If it's "software developer", "software architect", "systems analyst", or something of that sort, it's your job to figure out and document the requirements. Talk to your users, watch them work, etc., then write use cases, user stories, or just plain old lists of what the users say the system should do and translate that to specs.
If you're "just a programmer", then you need to convince them to hire one of the above (or get a new job).
If you're actually both, which in many companies is the case - then do all of the above.
There's endless books on the subject, from CMM in Practice to Extreme Programming Installed and everything in between. Go read some.
Did your chemist flagellee by chance want a general solution that he could apply again and again, without firing up dbase and typing in queries again and again? Did you solve the problem or fight the fire?
Getting data in an open format is very important to getting real work done.
Look it up, the results are astounding. At least compared to crying on slashdot that you have to do requirements.
I'm not sure what use sociology would be in designing accounts software. Care to enlighten us?
Confucius say, "Find worm in apple - bad. Find half a worm - worse."
I second Mike Cohn's advice. I haven't read his books, but I've heard him speak on multiple occasions, and I find his approach to be eminently practical.
I take that a step further - don't just go work with the users. Take some time to do the users' work.
As you see by my anecdote, that is exactly what I did and hence my original statement implied that. "Work with" can also mean "doing the same work." Note that trying to do the users work without knowing how to do it is going to get you nowhere, which is why you need to work with the user to do the work. How else are you going to learn? Read about it in a book? Search the internet?
Actually creating technical specs is worth a book in itself; check the article on Joel on Software.
You can learn the process... and the mockups are actually a good start. You just need to go further and develop the app. by thinking "what happens behind this fascade". Also, if you don't have any formal accounting qualifications yet, get your boss to pay for them, since that's the type of work you're doing... five years later you'll probally be glad you have then when you're... making more money than you can count, or whatever.
Alan Cooper: "The inmates are running the asylum"
B$
Unfortunately, in-house software dev rarely rates a usability engineer or whatever rarified form of analyst you propose. I understand the basic issue here, though: the original writer never received the kind of indoctrination you get in a more professional shop. This is not really a knock as much as it is praise for the long-gone development team of AT&T, for example, that had excellent day-one training for new hires.
We are almost out of analysis for the first iteration of a major internal project, global in scale and scope. We have over 1200 user requirements, and we're going to get more over time. The requirements gathering is always the easy part. The hard part is analyzing them and trying to figure out if we understand what they said a week later. Now try to get consensus among four continents, and you can see that it's really just communication and facilitating discussion. It's no wonder people fail to do it, because it's so diametrically opposed to CS course study.
That actually sparks a thought (take note!): what if as part of your CS course work you had to take a class that involved lots (and lots) of interviewing people? Would criminal justice departments or psychology departments have that? We could sure use a re-orientation around the human elements of requirements and analysis.
-BA
That's what I like about languages like smalltalk. The ability to tweak a running system.*
*Naturally you have to be careful not to break anything, but that's always been true about any running system. Just keep a copy of the original image and you're ok.
You may want to give these tools a try as well.
Comment removed based on user account deletion
If you are a programmer, you have to have specs. If you are an analyst or architect (or a consultant), you must engage in requirements gathering and business analysis, finding out what your client wants and how they do their work right now. If you work as an employee, consult your job description. Note that requirements gathering is a specialised process, and is very difficult if you have to design software for professional or scientific use (such as accountancy software or engineering applications), so it would be a good idea to cooperate with a specialist (e.g. an accountant) or read some introductory books about accountancy so that you can understand what your clients does right now. Oh, and good luck!
Your users don't really know what they want. Chances are they view you as some "smart computer guy" who "has all the answers (tm)". They're primarily talking to you because their boss told them to talk to you.
If you had someone generating requirements for you, (like I have in the past,) he'll become disconnected with reality and give you a document that really isn't useful. You'll build a machine that has 4 tires and a steering wheel, but it won't be a car... He'll assume that a major task is trivial, or that a computer has some magic AI, and thus add requirements that have very little ROI.
You're lucky, in a way. You have the oppertunity to do rapid prototypes! You can put a prototype rather quickly into your users' hands. By putting a prototype into their hands, they'll be able to give you feedback like, "I need a button to do this," or "this is too confusing." It'll give your discussions a frame of reference, and help quickly prioritize the most important features for success.
No, I will not work for your startup
Well, I would go to each area you are writing an app for, and see what the current process is. Ask people if they have any ideas for improvements. If it looks like some info is the same on nearly every form, ask if they'd like some sort of shortcuts for the most commonly used entries. Ask if there's any part they wish was faster and see if you can help that out Then, I'd hack up a prototype with ruby on rails or something -- no security yet, but also ugly and unpolished so some PHB isn't tempted to put this insecure version of the app into production. Show this to the people that'll have to use it, point out it's ugly, but have them test-enter a few points into this (while also using the "old" method) to see if it's workable. Find out if it'll really do what people need. Then polish it up, or rewrite an app that behaves similarly using your preferred language(s).
Were I work, we get in 100's to 1000's of PCs a week, pull and 3-pass wipe the hard drives, put them back in the machines that are worth it and sell them. Our highers up want full tracking of PCs as they come in matching them to department and ID tag on the computer (despite there being no tracking before they come to us anyway..) We haven't done this yet, it'll require scrapping the POS system (which is written in Access 97, so it probably should be anyway) and installing a system or 2 where machines come in, which we are being given no budget to do. The hard drives themselves are tracked though.. the system is quick and elegant. It's using a web form, php, and mysql. Once the drives are 3-pass DOD wiped, the brand is scanned off a sheet of paper with bar codes for each brand (or typed in if it's a weird brand like Imprimis -- yes, we've gotten drives that old), a 2nd sheet is scanned for size (or typed if it's odd), and then the serial # is scanned off the drive. About 10 keys are remapped to tab so the user can kind of thwack any key in one corner of the keyboard instead of specifically having to aim for tab. At this point, a label printer spits out a label. This is attached to the drive. The highers up seriously were expecting us to this by hand.. yeah, hand-writing 20,000+ digits per week into paper forms sounds awesome.
[YACA] Think about a car, it actually has very few features. Press that pedal, the engine speeds up. Move that lever and the ratio between engine speed and road speed changes. I'd reckon less than twenty variables describe it - not counting accessories like the radio and aircon. What's more it's familar - most people can drive, or they've seen someone do it. So for a car, we know what it means when we say it works. [/YACA]
Any non-trivial software is much more complicated in functionality terms. Especially to a programmer who's trying to build something he's never 'driven'.
It's true I tell you, feller at work's next door neighbour read it in the paper.