What Are Your Recurring Requirements Document Headaches?

Question

I seem to be forever going back to the Colouring-In Department (Marketing) and other product teams within the company I work for, trying to impress upon them what a software developer needs by way of well-formed requirements.

This isn't in technical geek-speak, either. It's plain English, lots of pictures and small words with a Word template I created to guide them through the information gathering process.

Yet I still seem to get a document full of nested tables with oodles of copy but no description of any functionality, references to non-existent screenshots and design mockups that look nothing like their related descriptions in the document.

While I appreciate that I am not dealing with technology-savvy people usually, doesn't there come a point where I can expect at least some basic level of effort and understanding??

What other stories of frustration and anguish are common out there? What levels of idiocy are us developers up against?

Answer 1

I think that the gap between engineers and non-engineers (customers, marketing, slave traders, etc.) is a little like the contrast between declarative and imperative programming.

Engineers realize that a computer does exactly what it's told and no more or less. The best description I've ever seen on that was in a national geographic magazine article from the 70s that tried to explain to people what it is that computer programmers do: they went with an example of how difficult it would be to program a child to cross the street.

Non-engineers see the computer as a tool that is supposed to get them what they need and figure out by itself everything that they don't specify. Maybe this is because they are used to working with people who implicitly do this for them when they request stuff. Maybe they just watched too much sci-fi where the computer always produces what you wanted it to.

I think that crossing the gap is an issue of politics and negotiation. As far as they are concerned, they know what they want (even though they don't really), and any help from their side is like getting into the details and micro-management.

Answer 2

At my company, we used to do more of a waterfall model with large requirements docs. After many iterations of this, it was becoming clear to everyone that it was not working. Marketing was not able to flesh-out every requirement in enough detail for the developers to program every feature, and project management was pretty much impossible. We've recently moved to an "Agile" Scrum methodology, which has been working a little better, as far as getting features out. At first, we put a lot of weight on the "user stories," but it's starting to look like even the smallish user stories are still hard to really nail down. I think my team is starting to come to the conclusion that we'll never have good requirements, so working closely with the product people and doing short iterations is really the only way to get features out that live up to the product expectations.

Answer 3

Before going into my frustration, I have a solution to the issue you have that works quite well for me. Have the business users describe the functionality as behavior. I find the user story (use case, usage scenario) work rather well. They know the process they are looking at, but often get bogged down in trying to give you a full answer. When you focus them on the user story, they will generally give you enough information, even if they do add data maps, etc., to fog up the document.

A common frustration for me is having the user try to fix language rather than focus on layout and flow of the user interface. I have solved this by moving to lorem ipsum, which they cannot read. This was a trick I learned from my design days.

Another common frustration is getting business users to realize you cannot box time, resources and features. Moving to an agile methodology solves this quite nicely, however. If they will let me time box two iterations (sprints, if you love scrum words), I can generally get buy in.

Answer 4

I have been in Waterfall (current company) model and agile structures and some strange ad-hoc hybrids and requirements capture has always been the weaker link in the chain.

There are no magic bullet here and I do not think a good word template however much time is speant trying to get it right will do the trick. But it is not hopeless. The main problem here is not only you do not speak the same language but they will not know how "shallow" or "deep" they must go into.

also, very often, they will not know exactly what they want (in my opinion one of the fundamental flaw of the waterfall model, but this is another debate) and will cover their ignorance with painfull amount of documentation.

There are two situations I have worked in that made the whole requirements capture pain go away.

1 - Usability testing on iterative prototypes. This approach works good in an agile setup but it can be coereced in a waterfall if the prototypes remain in the specification phase. Get a prorotype of the user interface for the functionnality they are after. Since this is the part they will be interacting on then it will help make their ideas clearer and will help you understand better whas is it they need.

and/or

2 - Actually sit with the customer and extract the requirements with them. Requirements are engineering documents for engineers to understand. I have rarely, if ever, seen requirements document correctly written (witht he PoV of engineering that is) if it is done by non-engineer. Having one to sit with the end user (or marketing departments) and write the document for them, with them will save you oogles of pain.

The main secret here is dialogue, nothing will beat a good constructive discussion with them. With it you should get enough information to get started. Once started then go back and test with them to fill in the blanks and stay on target.

But to expect them to give you a document that covers everything and anything you need to know to build the system is bound to fail, there is just no bridges for the engineering chasm that split you and them appart.