I am going to start a little side project very soon, but this time i want to do

Question

I am going to start a little side project very soon, but this time i want to do not just the little UML domain model and case diagrams i often do before programming, i thought about making a full functional specification. Is there anybody that has experience writing functional specifications that could recommend me what i need to add to it? How would be the best way to start preparing it? Here i will write down the topics that i think are more relevant:

Purpose
Functional Overview
Context Diagram
Critical Project Success Factors
Scope (In & Out)
Assumptions
Actors (Data Sources, System Actors)
Use Case Diagram
Process Flow Diagram
Activity Diagram
Security Requirements
Performance Requirements
Special Requirements
Business Rules
Domain Model (Data model)
Flow Scenarios (Success, alternate

Explanation / Answer

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:

Purpose
YES, write this. Keep it to 1-2 paragraphs, 1/2 page max.

Functional Overview
MAYBE. Only if it adds value to everything else.

Context Diagram
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.

Scope (In & Out)
NO. Your context diagram does this.

Assumptions
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.

Use Case Diagram
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.

Process Flow Diagram
MAYBE. Only if it adds significant value, else you are wasting your time.

Activity Diagram
MAYBE. Only if it adds significant value, else you are wasting your time.

Security Requirements
YES - if relevant.

Performance Requirements
YES - mandatory. Must say what the thing must do (and with what level of performance).

Special Requirements
MAYBE - if there is anything special.

Business Rules
MAYBE - if useful.

Domain Model (Data model)
MAYBE - if useful.

Flow Scenarios (Success, alternate

Related Questions

Navigate

• Browse (All)
• Browse I
• Subjects

Integrity-first tutoring: explanations and feedback only — we do not complete graded work. Learn more.