How do I write a specification? [duplicate]

Question

Possible Duplicate:
how do I write a functional specification quickly and efficiently

With so many projects changing halfway - and clients assuming much can be changed at no additional cost - I would like to start writing specifications. However, I have not done this before and do not know much about the basics. Where do I start? Are there often-used formats or templates for writing specifications? Does the programmer write this, does the client do this, or do both write this up? Any places where to see sample specs? All advise on how to get started is welcome.

Answer 1

There are entire university courses dedicated to requirements engineering, so a full discussion is beyond the scope of this question. I can, however, point you to some resources that should be helpful to get you started. I would suggest you poke around, both in what I provide and in other resources, and try to focus on more specific areas.

The textbook used in my requirements engineering course was Software Requirements. I also purchased an addendum to the book, More About Software Requirements. They tend to be more about requirements in plan-driven and documentation-heavy methodologies, they do discuss user stories and use cases in addition to formal requirement specification documents. They also walk through requirements elicitation techniques and vision and scope as well. The author of these books has a site, Process Impact, that has some resources as well, including various templates and guides.

If you are looking for more templates to follow, I usually recommend the ReadySet Templates. There are various templates to follow for different activities and phases of the lifecycle. Be sure to tailor them as appropriate to best fit into your development process.

As far as who develops the specification, it depends on how the project is structured, but usually it's a collaboration. I've seen where the customer knows what they want and they work with the development organization to develop a vision, scope for the work, and requirements specification. I've also seen where the customer has documents that specify the business and operational requirements and development organizations work with that to develop system requirements that can be used by engineers.

Answer 2

If you have never written a specification before, start small. A short text about the planned processes, the most important database tables and/or classes and a few sketched screen layouts, together with all the hard facts (descriptions of import/export formats etc.) can work wonders.

It's all too easy to fall into analysis paralysis when you focus too much on doing it right, using UML to it's full extend and having every arrow with the right kind of tip. Specifications can literally grow to any size when you have no idea how much detail is enough.

Answer 3

Perhaps a great first step for you is to institute simple change control. The next time a client asks for a change, tell them that this is a change that was not included in the original estimate. Tell them if they would like to have the change to send you the details of what the want in an email and you will get back to the with a price.

The benefit of this is that it makes explicit that changes are occurring. By sending an email, the client is acknowledging that it is in fact a change.

What is likely to occur is that this will cause the client to ask for fewer changes. At a minimum it will cause them to understand the extent of the changes and make explicit wat was involved.

It is up to you if you choose to ask for additional money for the changes, some may be simple enough that you will throw them in for free like you do now. The difference would be that at the end of the job you have a paper trail of the extra value you delivered which should help you win repeat business. For bigger changes, definitely charge.