I am often asked to write a requirements document for a new piece of work. I write requirements using user stories. The list of requirements is then used as a contract with the client denoting the functionality that will be delivered. The temptation them becomes to add more and more detail and more and more stories in an attempt to define a water-tight specification that rules out any expensive mistakes.
The problem is user stories just don’t seem well suited to this task. Can anyone offer any clarification on the role of user stories? For example, is the same user story appropriate for client, programmer and the author of a functional spec?
Regressing a little, perhaps I’m also asking what is the best way to define a contract of what will and will not be delivered in a software project?
Even the United States federal government can’t write water-tight software specifications.
There’s a natural conflict in contract work. The developer wants to be paid a reasonable amount, while the customer wants to know what the software will cost.
If the customer has no idea what they want, the first project should consist of developing a requirements document. The contractor and customer should negotiate small, achievable projects that eventually get to the working software project. That way, both parties feel comfortable with the process.
If the customer has a good idea what they want, and the contractor is reasonably sure he or she can develop what the customer wants, then images of screens and reports give both the customer and the developer a good idea of the scope of the development process.
In my simplistic eyes, there are 2 general types of detailed ‘artifacts’ surrounding ‘requirements’ and ‘scope’ of a project, or a part of a project.
- Requirements artifacts – what the customer needs / wants. Requirements are generally quite utopian, and will grow and change as the customer’s business changes. User Stories, outputs of JAD sessions, Use Case Models, screen wireframes, and other documentation focused on the customer’s point of view all fit here, IMO. The wording is typically in the domain of the customer or users of the system.
- Contract Specification artifacts – watertight, itemized ‘definitions’ of all items which are to be delivered in scope of a contract. These include both functional and non functional ‘specifications’ (i.e. including qualities like performance, security, robustness, choice of technology, etc). A specification doesn’t promise to meet all the customers requirements, and often a specification is limited to a partial piece of the system (e.g. a RUP ‘generation’ or iteration, but probably a bit more than an Agile Sprint). Specifications are much more technical in nature (e.g. will include interface definitions, performance commitments, and possibly ‘signed off’ screens). And as you’ve eluded, a contract is often best stated as what is NOT in scope of delivery. Any salesman knows that customers hate being told what they aren’t going to get.
On a fixed price project, it is suicidal for the developer to agree at the requirements level, yet at the same time, it can be very difficult for a developer to recover the cost of a specification, and you will often scare away unsophisticated customers with specifications – they often view it with skepticism due to the technical jargon and legal angle of the document. But with sophisticated customers (e.g. those used to dealing with highly technical projects, e.g. NASA, ESA etc) this level of definition isn’t a problem at all. But the additional formality comes at a cost – delays are often incurred while the documentation goes to and fro until it is finalized.
As a result, I believe the general idea is to move engagements with most customers away from fixed price entirely, and toward a paid-time project development basis, using tools like Agile and Scrum to ensure that the team is delivering at maximum efficiency and transparency, and the team is usually closely integrated with the customer, e.g. on the customer’s premises and / or with customer resources in the team. This way, the customer can ‘see’ that everyone is pulling their weight, the customer has the ability to change direction of the project in between sprints, and tangible, testable software is delivered at regular intervals. This way both parties can evade the ‘Contract Specification’ entirely, and work on a mutual trust basis.