Hi,
What are the general, traditional steps/stages to software development, or more specifically, specification writing?
I know of concepts like waterfall method, gathering specifications, use cases, etc. But I want a more formal explanation to it all.
The book Code Complete has practical coverage of this topic. See http://cc2e.com/
I found companies generally either:
Don't do specs.
Have a spec template. Each spec looks like all the others (ie "standard") - they all have the same sections.
I don't like either. Each spec is different. Trying to make it fit a rigid template is like writing a book to a template - a children's book is different to an adults book is different to a cooking book is different to a ....
Some specs need to go into technical details (like file formats), but others are fine when presented from the users point of view (a button that when clicked does x).
The best specs I've seen are ones that I can take and do what it is without having to ask the spec writer any questions. If I have to ask questions then I consider the spec to have failed. The spec should answer all my questions.
When I'm writing a spec, I always print it out and read it (I find more errors when it is printed). Then I leave it for a day and read it again. If I find any errors or think of anything it's missed I update the spec, print it out and read it and leave it for a day. I keep doing that until I don't find anything wrong with it.
A spec should be easy to read. I was once handed a 120 page spec with no table of contents and no page numbers. I asked the spec writer to put in a table of contents and her answer was "no, I want people to read through the spec to find what they're looking for since then they'll read more of it". I wasted a lot of time looking through that spec looking for stuff. That was a bad spec.
Whatever method you use to write the spec doesn't matter - the outcome is the important thing. The spec should be easy to read and answer all questions.
We use a basic template for our specs, but we have some flexibility as to whether all parts need to be included. I usually include a table of contents and if needed a table of figures (for screen shots, error messages, etc).
Sometimes we start with a feature or enhancement, write up a complete spec, then do the coding. Other times we'll start coding it then go back and flesh out a spec after the fact. Both approaches work for us. Often our specs describe how the feature will work from the user's perspective, though we sometimes include technical details like new table definitions or changes to existing classes/modules/forms.
I agree with Dan, if the end result is useful to those who read it then it's a good spec. I do think it's good to have some kind of agreed-upon format, so you can quickly find certain kinds of information when looking at multiple specs.
Joel has a series of articles on this topic, his advice, which I agree with, is to write short clear specs for important features and pass them on to the devs to work from.
What you may not want to do is try to spec out everything across the entire project when you're getting started. Stick with higher level specs, and work your way down to more detail when you're ready to implement a feature. That way you shouldn't have as much document overhead, and there isn't as much chance of your spec becoming obsolete before development (if you had done it weeks or months ahead of time).
What type of specs do you mean? The right spec for you to use will depend on your team, who will use the spec and any project documentation requirements.
Specs should be tailored to the target audience and should consider the expected lifetime of the document. I have used Functional Spec and Technical Specs. For a Functional Spec the main target audience was the client and for the Technical Spec the target audience was the developers, and IT team (for deployment).
The Functional Spec was not usually maintained after development started. Generally the Functional spec was built before the project started and was used to assess the size of the project. One architect I worked with wrote a kind of Functional Spec in Power Point. He took it to all his meetings, technical and non-technical. It was full of easy to read diagrams and pages with dot points that we used like a mission statement for the project.
The Technical Spec sometimes was maintained throughout the project. If kept up to date it could then used for reference for maintenance.
I agree with @Dan that each spec is different, and may look very different. To me what is important is having a consistent process that your stakeholders are all happy with, and any tools (such as BRS templates) that will make their life easier.
the following is a bit of a hack of a similar question .
The steps as i see it are;
1) Business Requirements Statement (BRS)
2) Functional Specification
3) Technical specification
The BRS covers what the business problems are, and what the requirements are around solutions, testing, security, reliability and delivery. This defines what would make a successful solution.
The functional spec details what is needed, how it should look, how long fields should be, etc.
The technical spec details where the data comes from, any tricky code that may need to be considered.
The customer owns the requirements. The developers own the tech specs.. and the functional spec is a middle ground. Testing is done against the tech specs (usually unit testing) then then against the functional specs (usually system testing) and then against the requirements (UAT).
The important part of this is that the developers still need to deliver to the functional spec, and most importantly the original business requirements. In reality the BRS is god in all of this and the functional and tech spec are just there for clarity.