Who (client or provider) should write the specifications document

Question

I have the opportunity to work on a project to create a phone app. I have been given a document that's about 60 words total. There are a couple of phone calls and SMS message too, but it's clear to me that I'm going to have to work hard, just to figure out how hard I'm going to have to work.

In the software industry, is it expected that the client will provide clear specifications, or is it the developer's task to distill all the bits of phone calls, emails, SMS messages and whatnot into a Specifications Document to be approved by the client?

I understand there needs to be some flexibility, but what is the expectation I should have for the documentation at the beginning of the project?

Answer 1

It is your responsibility to gather enough information to make it reasonably possible to write an application that substantially fulfills the client's expectations. Usually that means going back to the client, asking the right questions and getting clear answers.

There are plenty of resources that will teach you how to gather useful requirement specifications. The most pertinent rule is this: "Every requirement must be accompanied by an acceptance test that, when executed, clearly and unambiguously indicates whether the requirement has been satisfied." If the acceptance test does not exist, it's not a requirement: it is a "feature" or "wish."

Software Development has a long history of unfulfilled expectations. Before you commit to an approved design document and write a piece of software that the client says is not what he asked for (this happens all the time), consider adopting an iterative approach. You and your client commit to rapid development of a series of prototypes; with the completion of each prototype, the client gets to provide feedback on the features he likes and the features he dislikes, allowing you and the client to steer the development towards a successful outcome.

Answer 2

The typical process is that the software development company work with the customer to define the specifications of the software.

How involved this becomes, depend on the commercial model...

Is the customer paying a fixed price, for a fixed specification, in which case you need to fully understand and document the specification, and have the customer sign off that this is what will be delivered for their money.

If the customer is paying time and materials. Then working in an iterative way, delivering incremental features with regular reviews with the customer can work well - but the customer will need to be more involved in the weekly planning - and helping to resolve specification gaps when they arise.

In my experience, finding customers who are happy to commission software without a fixed definition of the end product, and no idea of the price is unrealistic - so you end up with giving the customer an overall estimate. I would then strongly recommend including in this estimate a 30-50% contingency, so the customer has budget in place for specification updates, undocumented requirements and implementation over runs.

If the estimate is significantly out, (takes over twice as long) the end result is likely to be a very upset ex customer.

Good luck!

Answer 3

It depends completely of what the customer is looking for and what was sold to the customer.

In an ideal world, the customer would now exactly and upfront what he needs. He would provide you a perfect specification with all the details and without any ambiguity. But how would such precise specifications be drafted ?

• Does the customer has the analytical skills to provide you with an in-depth, state of the art analysis (e.g. with the means of a big corporation) ?
• Could the subcontract the analysis to independent consultants (e.g. sometimes this happen in public procurement) ? He would then provide you with this output (hoping that it's understandable and nothing was forgotten) !
• Or should he subcontract this analyis with together with the implementation work ?

To me, the two first alternatives sound very much like a waterfall model. It's certainly a possible option. But if would be the best approach, then the Standish Group would never have published its project chaos report. And nobody would have invented iterative and agile methods !

The fact that the customer gives you a relatively short document with his goals and a high level description has the following advantage:

• you have the the freedom too chose the best approach to refine the requirements (whether waterfall or agile)
• you can propose more innovative solutions than the customer can think of (Ford used to say: "If I had listened to my customer, I would have looked for faster horses")
• the customer avoids the risk of ping-pong game between his analyst and his implementer in case of quality issues,

There's one condition however for this to work: the customer must be ready to contribute actively to the project, be it for the requirement gathering or for interactive session to validate iterative product results and confirm orientations.

Answer 4

Responsibilities for delivers are typically called out in Statements of Work (SOWs).

If this has been left undefined, I recommend insuring that a requirements document is assembled that can be used communication and collaboration. Also, be careful of assuming that all project participants understand or even have read the document.

Answer 5

It must be an iterative process. Who ever pays the bill gets the final say, but often they don't know what to ask. Come up with a rough draft, and touch base weekly with progress.

See Agile development