What vs How

http://www.snjtechconsulting.com.au One of the biggest dilemma's BA's face is how much detail to include and to satisfy the users representatives, the business and the development team. It is best to avoid detailed design like the right hand side of the above diagram, use cases should never be 'fully loaded'.

Most of the time you will find that the essential software requirements are often stable enough, however the design associated with the requirements is often very volatile and shouldn't be described too much early on.

Business analysts must keep their thoughts in the problem domain for as long as possible and resist becoming fixed on designs, screens or layouts until they have understood and conveyed the business domain comprehensively. There is nothing worse than spending days and even weeks on design for a functional requirement and then be told that 'piece' of functionality isn't required anymore.

What level of detail must a business analyst describe? And how much is too much?

The more you document, the more you will have to change. Scott Ambler says that “barely enough is good enough”. Business analysts and application development departments can unintentionally abuse use cases much more than they need to be. Most would agree that you do not want to build the system on paper first and try to think and incorporate every single viewpoint and must have design requirement (buttons, backgrounds, URL’s etc)

Most of the time as history has proved, too much documentation is simply a waste of time and money. Why? Well because during this ‘discovery phase’ it is human nature to think, discuss, validate and reject many ideas, but by documenting most of these even in a simple format I have seen some BA’s basically document the requirements specification at the command of the programmer, detailing every single error message, the exceptions and technical components called. At this point it is obvious the BA has lost his/her role in the project and has become a “gofer”. The requirements specification normally describes the business and user functional requirements. Real software design doesn’t usually start at this stage of the project and maybe the BA has been roped into design considerations from a simple harmless discussion.


Use cases or documentation development?

Have you seen too many alternate flows or exceptions in use cases? I have seen up to 20 different alternate flows for some use cases. Of course many error messages listed in use cases are alternate flows from the perspective of the programmer, certainly not the user. Use cases should always be written from the perspective of the user.

Many alternate flows are not within the problem domain of the user trying to achieve a goal. They should really belong in an implementation document and need not be shown to user or business representatives for the purpose of signing off the functional requirements.

What issues have you found when working with requirements documentation? Please share your stories.