What you suggest is fine from the point of view of the Systems Engineering purists.
(There will be a few Agile devotees who think its all way overt the top... and you should just get out and do stuff with the usual reviews, etc).
However, you need to take into account what you are doing, and who you are doing it for.
Doing a project for yourself is different to doing it for somebody else - for money.
When you work for somebody else (either in a company or on contract) the ONLY means of communication are speaking, and writing. (Ultimately there will be a product or result which can be assessed.)
The whole point of a specification is to try and reduce the cost of making fixes and changes that come later. You may have seen the graphs showing cost of making fixes at different stages of a project, it goes something like this:
A fix made to a dumb idea costs $1
A fix made when the dumb idea made it into a specification (that has to be updated) costs $10
A fix made when you have built a prototype costs $100
A fix made about the time you are doing an acceptance before shipping costs $1000
A fix made after you have shipped and pissed off your customers costs $10000.
So what you write in a specification is pretty important.
To argue that you should have no specification at all is naive, foolish, and probably dangerous.
One of the biggest problems you have in writing a specification is knowing when you have gone too far. This varies depending on the size of the project. For example, a project taking 1-2 people about a year should have somewhere between about 2 and 4 WEEKS in total spent on specification... which includes the investigation of feasibility... the spec to be written by the people who actually do the work not some high falutin analyst type who does not know the gory details. A project taking 10 people 2 years needs a lot longer.
Now for some comments on your various points:
YES, write this. Keep it to 1-2 paragraphs, 1/2 page max.
MAYBE. Only if it adds value to everything else.
ESSENTIAL. Shows ALL inputs and outputs. Shows context. You can (and should) spend a reasonable amount of time on this.
- Critical Project Success Factors
MAYBE. Surely if the project meets the requirements its a success. I think this is not really needed.
NO. Your context diagram does this.
YES. Try and keep it brief.
- Actors (Data Sources, System Actors)
MAYBE. This sounds like technical gory bits of design to me which should not be in a FUNCTIONAL specification.
MAYBE. Put this (these) in an appendix. Explain with words. Try to keep these to a small number. I have seen suggestions that a project should have not more than 8 Use Cases explained in detail. Don't cover all the "unahppy" paths or you will never finish.
It is very rare for any piece of s/w to have a single Use Case / Use Case Diagram.
MAYBE. Only if it adds significant value, else you are wasting your time.
MAYBE. Only if it adds significant value, else you are wasting your time.
YES - if relevant.
YES - mandatory. Must say what the thing must do (and with what level of performance).
MAYBE - if there is anything special.
MAYBE - if useful.
- Domain Model (Data model)
MAYBE - if useful.
- Flow Scenarios (Success, alternate…)
MAYBE - if useful.
- Time Schedule (Task Management)
NO. This is not what should be in a spec. Its about schedule, planning, etc.
MAYBE. Goals are not requirements, they are vague fluffy wouldn't-it-be-nice things, which serve to muddy the waters. Try and avoid.
YES. Essential. Says what the thing must do.
NO. Part of planning and management, not the requirements of the thing you are making.
Explanation: I've been writing specifications for products, software, and complex systems for over 15 years. All commercial stuff. Mostly commercially successful and made a lot of money for various employers. Including specification for Agile s/w development where you still need a spec before you leap into the development. The ACTUAL development can be done in whatever process you want, but in the end you must have 3 things for success:
Know what you want to do. AND WRITE IT DOWN. (Thats a spec.)
Do stuff to meet #1 above.
Do some level of acceptance testing of the thing against the spec (which is essentially "did you do what you said you would do").
I see two good possible approaches to to this problem. However, it's important to realize two things. First, requirements engineering is hard work - turning an idea into a formal specification that is enough to build a system takes a lot of time, effort, and practice. Second, if you have good requirements (in any format, from a formal specification to less formal user stories and use cases), it will be significantly easier, cheaper, and faster to actually build the software (and build it right earlier).
If your friend is either going to be asking for numerous software tools to be built or intends on contracting them out, he should learn how to write software requirements, at least at the level of business objectives and concept of operations. The two leading books on software requirements engineering are by Karl Wiegers - Software Requirements (2nd Edition) and More About Software Requirements: Thorny Issues and Practical Advice. I would expect that most people he would hire would want some kind of document describing the system, at least at a level of business objectives or concept of operations, and these books go into that. They also go into the how and why of other aspects of requirements engineering that I would suspect a good developer would go through early in the project.
The second option would be to either hire someone with experience in software development and requirements engineering (and perhaps even some kind of systems engineering or system architecture) to understand the problem space and determine where software solutions are needed and where software solutions wouldn't be beneficial, write the documents, and perhaps even oversee or carry out the development effort. However, this would probably be more expensive and amount to hiring a full-time software developer for an extended period of time to develop not only the system requested, but the requirements and architecture needed as well.
Honestly, I don't think what your friend is experiencing is that uncommon for someone who doesn't understand the software development process. I also don't think the blame lies entirely on him, either. If the first software project didn't have good requirements, the developer(s) that it was outsourced to should have clarified, refined, and documented the requirements. Frankly, I'm not sure that you are the right person to get involved, either, if you aren't willing to put in the time or the effort to work with the non-technical user/customer and develop good technical specifications (this is a key role of anyone performing requirements engineering in any engineering discipline).
I think the optimal solution is really a combination of my two options. I think that your friend (and perhaps you, as well) should learn about what is involved in requirements engineering and the benefits that having solid requirements can bring to a project. You, as a software developer, should also become more familiar with requirements engineering and how to elicit, document, analyze, and manage requirements as appropriate for software projects - it's really a valuable skill for anyone doing work at any part in the software lifecycle.
Best Answer
Did you read part 2 of the article or his sample specification? They embody a couple important principles when writing a specification.
The best advice is to write enough so that you are clear on what you need to do. If you have open questions, document them in the spec and get answers from your client. Once you adequately understand what's needed stop.
If you are not careful, the document will take on a life of its own. It should have one purpose, don't add anything to the document that doesn't fit that purpose. It should be easy to maintain. If you have your entire detailed class diagrams in there along with other details that really belong in a unit test, you will either abandon the document because the upkeep is too much, or you will never get the project completed.
About Writing
Writing for people is hard. In fact, the two hardest things about writing is knowing how to start, and knowing when to stop. In the beginning you just have to do something. My advice for dealing with these two hardest aspects is: