Forgot your password?
typodupeerror
Programming IT

Getting Accurate Specifications for Software? 147

Posted by Cliff
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.

Getting Accurate Specifications for Software?

Comments Filter:
  • he's right (Score:5, Insightful)

    by Anonymous Coward on Wednesday March 07, 2007 @06:40AM (#18260174)
    Your boss is correct: it is your job to get accurate specs.

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

      by KDan (90353) on Wednesday March 07, 2007 @06:49AM (#18260224) Homepage
      Absolutely. Get your ass off your chair, walk over to the users, and talk to them about what they need. Then write yourself a detailed spec if you feel you need it. Then turn that spec into some paper-based mockups and walk the users through it. Then make any corrections needed. Then write the software.

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

      Daniel
      • Re:he's right (Score:4, Interesting)

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

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

          by Richard Steiner (1585)

          Are there actually companies that write proper specs? I've only been doing IT for 19 years and I have yet to find any place where it actually happens.

          At most of the places I've worked, the creation of specs is an interactive iterative process between us (the developers) and the users. Sometimes it starts with an idea, sometimes with a detail write-up, but most of the time the gory details take a little while to mail down and will usually get implemented in code first and then changed over time based on

          • by qwijibo (101731)
            Document the system after the fact - that's the funniest post I've seen in weeks. We all know there's no business case for documentation once the system is working and live. =)

            I'm not sure if your 18 month cycle between versions sounds miraculous or scary. It would be nice to actually follow a project through to completion, as opposed to shipping the abortion which is the most cost effective approach. However, I worry that an environment that allows that could ship the same quality, but have a lot more p
            • Document the system after the fact - that's the funniest post I've seen in weeks. We all know there's no business case for documentation once the system is working and live. =)

              Commercial software development for external consumption is VERY different from in-house software development, both in terms of the nature of said development (different lifecycles and methodologies), and in terms of the nature of documentation required.

              My Unisys ADSC example was an example of a mainframe software house releasing

        • There is, in fact, at least one company out there that writes good specs. I had the pleasure of working a few contracts for them. I never had more than one or two small questions about what they sent me. They sent it, I wrote it, they paid me. Their customer always got it on time and with no surprises. It was surreal.

          Devon
      • Re: (Score:3, Insightful)

        by Zarf (5735)
        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.

        Damn straight. All of us who get specs like these are in a special place. We have to bridge both the Analyst and Programmer jobs. If you are lucky the person who writes your specs won't go on a power trip and scream at you if you don't write exactly what they put in their word document. If you are lucky you have been given the chance to f
        • by smbarbour (893880)
          We have to bridge both the Analyst and Programmer jobs.

          There is actually a job title for that, Programmer Analyst, and supposedly it's the highest paid non-management IT job there is. Of course, I'm not being paid anywhere near what the title should pay, and I also handle desktop support, database administration, security administration, backup administration, report development, systems administration, etc.

          I am the highest paid non-management IT worker in my company... but I'm also the ONLY non-management
          • by AuMatar (183847)
            Job titles mean jack squat. You do what needs to be done. I have never had a programming position in which I wasn't a coder, architect, analyst, etc. As a programmer your job is to write the software your company needs. You need to be prepared to do any of those steps, regaurdless of title.

            Now money is another thing- if you aren't getting paid what you think is fair for your experience/skills, ask for a raise or look for a new job. But don't expect that things will be any different elsewhere.
            • You need to be prepared to do any of those steps, regaurdless of title.
              ... or your experience, training & ability.
              • Which would be gained via proper preparation, i.e., seeking out the requisite training, mentoring, study materials, etc., right?

                To your point I would agree that one does not simply unilaterally implement a new project methodology, regardless of project size, and regardless of experience, training or ability. Any solid methodology will involve stakeholders across the organization, stakeholders who will need to form an understanding of, and an appreciation for the proposed change. With this appreciation, an I
                • seeking out the requisite training, mentoring, study materials, etc., right?
                  Except for the "no time for training - we need you to do it - now!" factor. Then it still needs experience to develop those skills - assuming he has an aptitude to start with. AuMatar's answer came over a bit gung-ho and with more than a hint of arrogance.
      • by Bamafan77 (565893)

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

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

        If there were a once-per-year +20

    • by Moggyboy (949119)
      Hey there AC, I don't think it's that clear cut. For example, I currently consult to a large insurance company, and part of my job is to take complicated mathematical specifications from our actuarial department and implement them in our calculations engine. Even now, after having to clarify the previous specification with them in endless meetings over the last three months, I received a new one this morning with the exact same problems - vaguely defined arguments in pages of calculations that assume I am
      • by russ1337 (938915)
        >>>> "part of my job is to take complicated mathematical specifications from our actuarial department......vaguely defined arguments in pages of calculations ........not to mention the annoying contradictory footnotes...."

        Wow, if you're having trouble figuring out how the Insurance calculations are carried out, then that leaves little hope for the rest of us 'customers' to figure out how to lower our premiums...

        It also shows that the insurers probably want to charge more no matter what
        • Re: (Score:2, Insightful)

          by DudeTheMath (522264)
          No, it doesn't "leave little hope". What it means is that GP isn't up to the job. What he's talking about is part of my job, too (turning pages of actuarial documentation into business calculations). GP needs to get erself some training so that what e thinks are "vaguely defined arguments" suddenly reveal themselves to be well-known, precisely defined shorthand for (occasionally) complicated actuarial entities.
    • 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?
      • by walt-sjc (145127) on Wednesday March 07, 2007 @09:23AM (#18260994)
        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.
        • by Bastian (66383)
          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 product
          • by walt-sjc (145127)
            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?
      • I'm not sure what use sociology would be in designing accounts software. Care to enlighten us?
      • Users just want their software to work.

        The problem is, they're incapable of defining what 'work' means. Usually, it equates to ESP or DWIM [wikipedia.org] or both.

        [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

    • 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 poste
      • yet you expect these people to write high quality accurate software specs. Why?
        Because they're the business people (specifically accountants) who will use the system, and to build it the programmer needs to know what the business rules are (i.e. what an accounting system should do)? That's what I would call a functional spec, which is an entirely different thing from technical spec.
      • by AuMatar (183847)
        I'd still write specs. You don't need a 5 inch think binds of specs, but specs have a few good points

        1)If you disappear, die, have a family emergency, quit, etc they still can hire someone else to write from the specs
        2)You won't remember everything. Writing it down will remind you of what you wanted to do a month or 2 from now.
    • Re: (Score:3, Insightful)

      by geoffspear (692508)
      Exactly. Submitter says "I design software..." but in reality he wants someone else to design the software so he can just be the codemonkey who programs it.
      • by sconeu (64226)
        No he's not. He's saying, "Tell me *WHAT* you want it to do, I'll figure out *HOW*".

        Parent should know the difference between requirements (spec) and design.
  • 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

    • On my last major project I was handed a detailed spec which I went and discussed with the client.
      Out of that discussion came spec 2.
      I started developing based on spec 2 but when we demonstrated some early milestones we suddenly had spec 3.
      My bosses are starting to get annoyed by this point, leading to spec 4, which is being implemented DESPITE the client pointing out things that would have led to specs 5 and 6.
      It's a crazy old world when the client doesn't really know what they want, or how to describe
      • by cyclop (780354) on Wednesday March 07, 2007 @07:58AM (#18260510) Homepage Journal

        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.

        • by Diomedes01 (173241) on Wednesday March 07, 2007 @09:07AM (#18260870)

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

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

          • by cyclop (780354)

            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.

            Being an "amateur", well, not always, because more often than note I had to refactor to allow things that it was never intended to do first. As of today I'm writing a plugin architecture and I'm rewriting the code to be everywhere as elastic as possible. Yes I should have done it first, but I'm not a pro developer and this is a good lesson I'm learning...

      • Re: (Score:2, Informative)

        by PhilipMckrack (311145)
        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
  • Well... (Score:2, Funny)

    by Anonymous Coward
    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!
  • by MichaelSmith (789609) on Wednesday March 07, 2007 @06:43AM (#18260188) Homepage Journal

    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:2, Insightful)

      by JonathanR (852748)
      If you know what detailed and accurate specs are, then you'll just have to sit down and write them. Bear in mind that this will involve a lot of interviewing of the prospective system users, to discover and document what they do now, and figure how best to implement it in your new system. I hope you've budgeted for this process in your estimate.
    • Re: (Score:3, Insightful)

      by Mikkeles (698461)
      This is correct. You require someone to fill the role of domain expert (aka subject matter expert) who can provide clear requirements of what has to be done and guides a UI expert in how the users are to interact with the functionality. If you have to fulfill both roles and don't know the users' business, then the system will probably be a turd regardless of how well the software is designed and coded.

      No, it's not necessarily your fault; however, programmers should become familiar with at least one area i

  • 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
    • Re: (Score:2, Insightful)

      by Diomedes01 (173241)
      I've found that you can iterate on a design document all you want, and create nothing but churn. I have found that it's far better to iterate with an actual prototype or mock-ups, because users don't think the same way looking at a sheet of paper as they do looking at an application. I've started using Ruby on Rails or PHP to do quick and dirty prototypes for our users (most of our internal intranet sites are Servlet/JSP based, but it's so painful we only want to do that piece once). Lately, my managemen
    • by Dan Ost (415913)
      Don't send them the documentation, send them an application that they can play with. Then, based on their feedback, write you're own detailed specs and update the application accordingly. As time goes on, your application will begin to have all the fleshed out features that the user needs, and, since the user was involved from the beginning, they'll be familiar with how the app fits into their work flow (this should keep them from asking for radical or contradictory changes with each iteration).

      Get the user
  • by Patrik_AKA_RedX (624423) <patrik.vanostaeyenNO@SPAMgmail.com> on Wednesday March 07, 2007 @06:44AM (#18260202) Journal
    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.
  • by Bloke down the pub (861787) on Wednesday March 07, 2007 @06:45AM (#18260204)
    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.
    • Re: (Score:3, Informative)

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

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

      The customer then has to agree to the spe
    • Re: (Score:3, Insightful)

      by mgblst (80109)
      Do you like meetings, because the only way to do this propertly is lots of meetings. Talk to them, talk to them some more, go away and think about it, and talk to them again. Talk about how you think it should go. Then get corrections. Ask lots of questions.

      WHen you start to get an idea, produce a document and then, in another meeting, go through it with them.

      This job is more about dealing with people, extracting little bits of information from them, getting them to think about the problem, more than progra
  • Impossible (Score:5, Interesting)

    by synx (29979) on Wednesday March 07, 2007 @06:46AM (#18260210)
    What you think your job is, and what your actual job is are two quite different things. Traditional software 'methodology' is bunk and doesn't work - this is why you are confused.

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

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

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

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

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

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

  • Yes. This is hard. (Score:3, Interesting)

    by WasterDave (20047) <davep AT zedkep DOT com> on Wednesday March 07, 2007 @06:49AM (#18260226)

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

    You're trolling, right? I hope so.

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

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

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

    Dave
    • 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";
      That's the perfect approach, if your sole goal is to find what their favourite colour is.
      • by rikkus-x (526844)

        That's the perfect approach, if your sole goal is to find what their favourite colour is.

        Which is why many mockup tools specifically try to make the mocked-up screens as 'functional' (read: ugly) as possible, to stop people saying 'I think I'd prefer it in minty buff'

        • GP was joking I assume, but many jokes are based on truth. There is a tendency to focus on the external appearance. I don't know whether this is because it's easier to say "put it there" or "make that green" than to actually think and articulate "I want to able to search based on name, zipcode and date of last order. Or any combination of those... and the date must be +- 4 days. Working days..."; it might just be plain human shallowness.
          I was at a client once, not directly connected with it but they w
          • by Dan Ost (415913)
            Fortunately, the appearance is the easiest thing to change. You can put a different interface in front of the user with each iteration without having to make any changes to the backend. Of course, by doing that, you keep the user from gaining as much familiarity with the app as development progresses (which usually hurts their ability to give meaningful feedback).
            • It doesn't matter how easy it is to change, it's still a distraction from what really matters - the functionality. The original question was about an accounting system. You can iterate 200 times with every shade of sky-blue pink with orange dots. But if you don't know up front the difference between a debit and a credit, and that they should balance, you won't know at the end either. Because the users won't tell you.
          • by walt-sjc (145127)
            GP was joking I assume, but many jokes are based on truth. There is a tendency to focus on the external appearance.

            I once worked with a new-hire programmer who had been asked to prototype some data-entry screens... He ended up demoing a UI with pink text on lime green background. When asked why he chose those colors, it turned out that he was color blind... He was taken off UI projects and put on back-end code :-)

            But yeah, I agree with the statement that the customer usually focuses on how things look rathe
    • Re: (Score:3, Interesting)

      by ivano (584883)
      It's not up to him to make all the decisions since it's not him that is taking the risk if the thing doesn't give the right answer or says the transaction is done when it hasn't. You want him to make the decisions that people higher up should be. Decisions need to be made by the person who has the risk. Sure testing, documentation, hell, even code-writing is his job, but then to insult him about his abilities and then talk about how fucken difficult the thing is is a bit back-handed.

      You even mention him

  • by cerberusss (660701) on Wednesday March 07, 2007 @06:49AM (#18260232) Homepage Journal
    Become an analyst, and hire programmers. Then:
    1. Don't make requirements anyway. Demand that they organize and create use cases and make them code the whole thing from there.
    2. If that's not possible, let a web designing agency do screen layouts. Then demand they only talk to the agency. Web designers are easy to talk with; they don't bother with stupid details. Actually, they don't bother with anything but the screen layouts.
    3. If you really must create requirements, create documents in PowerPoint. Make high-level, short and non-descriptive requirements. It's quite easy to design a system when you're in orbit instead of both feet on the ground.
    4. If you haven't driven the project into the ground, create documents in Word. Word offers fantastic opportunities! Use track changes, nested tables, extremely large tables, bizarre macros, hidden notes/comments, etc.
    5. Wait with submitting for review until you have a nice stack of documents. It's so much more economic (for you).
    6. Do NOT refer to any other requirements. Just copy/paste and then make small changes.
    7. Require prototypes in VB. Later, you can ask them what's taking them so long.
    8. They want to MoSCoW your requirements. Conduct several meetings on hot, sweaty days and slowly but surely make them understand that each and every requirement is a must-have.
    9. Make it difficult to let them get the latest requirement. Make it easy to get confused with old versions.
    10. Make circular requirements. But don't make it too obvious: make a chain of, say, 10-20 requirements and only THEN refer back to the first one.
    11. Make the versioning consistent with the 'Naked Gun' movies: 1, 2, 2-and-a-half, etc.
    12. Never uniquely identify requirements! That way, it's too easy for analists and developers to refer and to maintain them.
    13. Make sub-requirements that are sometimes numbered, sometimes with characters, and just for the hell of it, drop in some bullets, too! NEVER, EVER make it possible to sort the requirements in any way. Make sure to use the auto-numbering in Word, but sometimes just type them in yourself!

      123. This is a major requirement.

      123.1. This is a minor.

      123.01A.1. Please refer to 782.5.1¾.1A.

    14. Hide major requirements in a very deep nesting:

      123.5.1.A. This is a MAJOR requirement.
    15. Requirements should contradict each other, but not too obvious:

      78.a7.A. A history should be kept for all items. Never should any item be permanently deleted.

      ... skip a version and 300 pages ...

      342.8. Wullywuz must always be permanently deleted.
    16. Make sure it's hard to reach you. Go live in another country. A different timezone is even better! Convince your boss to outsource to an offshore company, which is easy, since it's all the hype these days.
    17. Include database tables in your requirements.
    18. When the project has already started, make major changes. But first talk your boss into thinking that the system without that particular change is basically worthless.
    19. ???
    20. Profit!!!
    • I'd be laughing if I wasn't crying. Brilliant. Bravo, good sir.
    • by Mark Hood (1630)
      You are my first manager, and I claim my five pounds :)

      Great write-up, but you missed one:
      123. This is a major requirement.

      123.1. This is a minor.

      123.01. This is a critical one, note that it's NOT the same as 123.1, or 123.10.

      Mark

      PS now just use Word for the requirements doc, and some requirements are auto-numbered as paragraphs so they move, and others aren't, so you can easily get:

      1. Introduction
      2. Requirements
      2.1 Important requirements
      2.1.1 Requirement 1.
      2.1.2 2.1-Requirement 2.2 ...
  • Forget it (Score:4, Insightful)

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

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

  • 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 elephant
  • 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
  • Try this one:
    http://www.oreilly.com/catalog/hfobjects/ [oreilly.com]
    Fairly simple, fun to read and far more useful than it appears at first sight.
  • Build a prototype (Score:3, Informative)

    by Lonewolf666 (259450) on Wednesday March 07, 2007 @07:05AM (#18260302)
    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.

    • by Tanuki64 (989726)
      But when you really build a prototype, don't build a good one. Make the part you are interested in nice and everything else really ugly. Stupids usually cannot distinguish between a prototype and the real deal.
    • by CaraCalla (219718)
      You don't even need a full, working prototype. Build mock-ups. Sit down with your prespective users and watch them try using your mock-ups. Understand what they are going to do with your product, is it really software they need? Understand what the guy who pays for the project wants. Return of investment?

      You really need to start thinking more like a designer, than a code-monkey. If you like being the code-monkey and if you like coding/engineering to specs, you should probably find yourself another job. Go f
      • In theory, my current company has design process (much reworked over the last year). It is followed in a rather perfunctory way so far, but I see some improvements creeping in. Also, the people writing the "design inputs" are gaining in experience and might eventually belong to the very few people who can write decent specs.
        There are other reasons to maybe switch jobs, but I will not do it over the lack of design process as it seems to get better :-)
    • What you all seem to have forgotten is that his boss has already given him a hard deadline for the delivery of the project, and that deadline is next Tuesday. He didn't say that in the summary. He didn't have to.

    • by oni (41625)
      you might have to say "no" at some point

      what I find far more useful than saying no is going through the whole process for any change. I go to a meeting and someone says, "oh, can you make do this extra thing?" And I say sure. Then I add it to the spec, call the new spec version 2.0, add a week to the timeline, and send the whole thing to them to sign.

      At some people, they step back and realize that they have asked for four years worth of development and they stop doing that.

      Now, after the product is deliv
      • If you decide you want french doors, the builder will happily charge you for that. Nobody would expect a change like that to be free.
        [Boss mode] Don't try and tell me that moving a few words around on a screen is the same as knocking a hole in a wall! [/Boss mode]
  • 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
  • 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 earnin
    • by Jellybob (597204)
      Agreed - get out of this situation now. I work as a web developer for an design agency, and the projects that go wrong are almost always the ones where our client contact is in sales.

      The worst is a multi-lingual site providing an online product catalogue. The site itself works, but getting translations is a nightmare. For example I was once given an Italian translation for the site, where the only reference point as to which words are translated is the odd German word, an =, and then a long list of Italian
  • by Johnno74 (252399) on Wednesday March 07, 2007 @07:21AM (#18260382)
    This is typical, get used to it - or get a job where this stuff is left to specialists, business analysts.

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

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

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

  • User stories (Score:4, Informative)

    by dwerg (58450) on Wednesday March 07, 2007 @07:31AM (#18260420) Homepage Journal

    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.

  • 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.

  • by ivano (584883) on Wednesday March 07, 2007 @07:41AM (#18260444)
    Scrum/Agile approach might be what you need since the feedback cycles force your client (the product owner) to think about what you misunderstood and what the product should become.

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

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

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

  • by johnjaydk (584895) on Wednesday March 07, 2007 @07:59AM (#18260514)
    It's a fact of life. Deal with it.

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

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

  • 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 [wikipedia.org] 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 [wikipedia.org] are usually brok
  • by JavaSavant (579820) on Wednesday March 07, 2007 @08:46AM (#18260760) Homepage
    I've found in the domain I work in (medicine) that story-driven projects tends to work pretty well, both in the way that estimation can be achieved and the degree of cohesiveness with which the "specs" or stories come together.

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

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

    Some good books on the subject:

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

    Single author (no, he's not a friend), but both books that have been fantastic for me in terms of taking a fairly unmanaged project group and making it a much less squeaky wheel within my department.
    • 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.
  • by s31523 (926314) on Wednesday March 07, 2007 @08:46AM (#18260764)
    Your problem is not unique. I attend an Extreme Programming workshop near where I live and a guy by the name of Richard Sheridan came to do a presentation on his companies technique called High Tech Anthropology [menloinnovations.com]. It was a great presentation and it is something you might try. Basically, you camp out in the users "Den" and observe them, taking notes and trying to understand how they work, what buttons they push, which user interfaces frustrate them, which things they like, etc. You then take this back and use it to publish your requirements specs. Some XP enthusiasts talk about bringing the customer in and having them work with them team, but Richard Sheridan makes a great point, that this can sometime lead to the users becoming more like engineers rather than the other way around (like the book The Inmates Are Running The Asylum). [uidesign.net]
    • by KillerBob (217953)
      Bah. My mod points expired. That's a very interesting idea... one I wish more programmers would follow up on.
      • Re: (Score:3, Interesting)

        by s31523 (926314)
        I deployed this strategy and it worked quite well. I was developing requirements for a UI on a flight system for the function of flight planning. I traveled a lot with our company plane and road "shotgun" a lot. I started bringing my notepad and jotting down what the pilot was doing with respect to flight planning. I also made several notes on the most common buttons and scenarios based upon what Air Traffic Control was telling the pilot. I flew in good weather, bad weather, heavy traffic, and light tr
  • 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
  • Meetings are bad, m'kay? E-mail exchanges headed "I need the specifications for the app" are even worse.

    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, di

  • 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
  • "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
  • 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.
  • 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
  • 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 so
  • 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
  • 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,

If a thing's worth having, it's worth cheating for. -- W.C. Fields

Working...