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").
Actually, I would suggest that you do not need a branching model, but rather a complete comprehensive approach to deal with the multi-dimensional constraints with regard to the system without branching. In practice, I believe it will always be a problem to maintain multiple systems that have some commonalities but will evolve differently in branches, so it is better to turn everything into a single system that will evolve as a whole, but consists of different configurations. This may appear to be too simplistic, but there is extensive research in this area, with a lot of successful industrial applications.
The name for this approach is Software Product Lines or sometimes Product Line Engineering. From CMU SEI's Software Product Lines page:
A software product line (SPL) is a set of software-intensive systems that share a common, managed set of features satisfying the specific needs of a particular market segment or mission and that are developed from a common set of core assets in a prescribed way.
The key idea is that every requirement, every milestone, every feature (a key term in this domain) is part of the complete system at the highest level. The actual systems deployed at various customers is essentially a collection of features. Each feature however is not just a physical component mashed into the system, it is defined as depending on or enabled by other features (so that by picking a feature, you may automatically include its dependencies, etc.)
Instead then of maintaining all these branches, you end up maintaining one system along with a set of customer-specific configurations.
It may be difficult or even impossible in practice to migrate to such an approach with a very large system, but even then it will be useful to investigate the approaches used in SPL in order to assess what approaches used there can at least be (partially) integrated in your work.
Some additional useful links:
Best Answer
Although quite heavyweight, whenever I have had to document a software design I usually went for the MIL-STD-498. I'm not saying you should produce (at least one of) each of the 22 document types it consists of, but rather to just choose one or two that make sense and then use the layout as a general guideline.
The one you might need is the Software Design Description (SSD). The nice thing about this approach is that you more or less dodge a discussion about whether your document will contain at least the required parts (it's one of the good things about using a standard that people tend to assume it's good for what it's for).
The documents tend to cross-reference heavily, but instead of writing all the other documents you can just define these things in-place in the document.