9

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…)
  • Time Schedule (Task Management)
  • Goals
  • System Requirements
  • Expected Expenses

What do you think about those topics? Shall i add something else? or maybe remove something?

I rode every single answer, and i would like to thank all of you for the useful information.

I am doing this side project for a company, and they spect from me a constant flow of communication and i will need to explain why i do every single thing, because i will have to administer the resources they will give to me. This will be my first func spec and as i said i want it to be useful, not just big and useless. I think this is something that has to be done, but i want to do it in the way that will be more useful for me and my team. Its bad that i we dont have a manager, so thats why i also need to take care about some administrative tasks...

Regarding to the agile programming, i think this is 100% compatible with the agile aproach. I am an Agile programmer my self and i honestly fell more confident when someone already did the thinking for me. I still Junnior, but i worked before as a Tapestry web developer in other projects, were the organization was a total chaos.

I dont agree i am doing a waterfall aproach, i think i am just trying to define some boundaries that will make the project being easier when the development starts.

sfrj
  • 317
  • 4
  • 13
  • 1
    Sounds like a waste of time to me. Do you think any of today's popular applications got started that way? Someone said "X sucks" or "Y could be cool" and they started building a solution. – kevin cline Feb 20 '11 at 00:52
  • @kevin cline: Without requirements in a written document, you will never produce what your customer wants. If you were a contractor asked to develop something and you did not write a specification, you would either go broke or end up in court. (Like so many large commercial s/w projects that go bad). A functional specification is immensely powerful because it encourages a great deal of thought before action. – quickly_now Feb 20 '11 at 02:22
  • 1
    If I were a contractor, I would never take the risk of giving a fixed price bid to produce a complex system with a specification more than a few pages long. I would much rather build and deliver the system incrementally, and bill at an agreed hourly rate. This minimizes the risk for both the customer and the contractor, and maximizes the feedback needed to produce a usable system. – kevin cline Feb 20 '11 at 06:18
  • @kevin - I guess you would never build more than toy applications then. 20, 30 or even 80% of an application is of no value to many customers. They either need it all or not at all. A plane that flies but doesn't land is not too useful. – Dunk Feb 20 '11 at 18:48
  • 1
    @dunk - Not all the features on modern jetliners were present at the dawn of airline service. An application can be useful before every imaginable use case has been implemented. – kevin cline Feb 21 '11 at 01:45
  • @kevin - thats fine if you are a contractor who can get a job like this. In my country, most (about 80%, or more) s/w and engineering development is done on the basis of a fixed price contract. Incrememental has its place, its also a wonderful way of featherbedding, which is why the trend to fixed price happened. It keeps contractors more honest and prevents padding. – quickly_now Feb 27 '11 at 01:29

5 Answers5

23

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…)

MAYBE - if useful.

  • Time Schedule (Task Management)

NO. This is not what should be in a spec. Its about schedule, planning, etc.

  • Goals

MAYBE. Goals are not requirements, they are vague fluffy wouldn't-it-be-nice things, which serve to muddy the waters. Try and avoid.

  • System Requirements

YES. Essential. Says what the thing must do.

  • Expected Expenses

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:

  1. Know what you want to do. AND WRITE IT DOWN. (Thats a spec.)

  2. Do stuff to meet #1 above.

  3. Do some level of acceptance testing of the thing against the spec (which is essentially "did you do what you said you would do").

quickly_now
  • 14,822
  • 1
  • 35
  • 48
  • This answer is pure opinion and has no scientific basis. There is no evidence that you need any of this stuff. – Dave Hillier Jan 05 '14 at 15:47
  • 1
    Sorry Mr Hillier, not true. Well established in the defence and aerospace business (go read about NASA s/w development processes). I've even been on courses that teach all this, and been a practitioner in one for or another for 30 years. – quickly_now Jan 08 '14 at 01:51
  • Wow you're so experienced you don't need to provide a single reference to prove that any of your assertions are true. In any case, I'm not saying there is no reason that you would ever need that stuff, just that you don't have any good reasoning as to why he actually needs this stuff. – Dave Hillier Jan 08 '14 at 11:26
  • Sigh. The question was about a FUNCTIONAL SPECIFICATION. This means you don't put in anything to do with resourcing, scheduling, work breakdown structure, etc. In the normal course of events that kind of information appears in a Statement of Work, and then has supporting information in a WBS, schedule, staffing allocations, etc etc. The best known, though these days perhaps a little dated, reference is Blanchard "Systems Engineering and Analysis". There are many editions, the later ones are probably best. – quickly_now Jan 13 '14 at 23:51
  • Whether a functional specification should be used for s/w development is a point a great argument - usually argued against by those who don't like being pinned down at a project outset. There are other "modern" techniques that are claimed to work better (refer The Agile Manifesto). Whether they do in fact work better is debatable; for example if doing a large development job for defence the customer might feel comforted with frequent builds but might not be prepared to fly them. And doing such a job w/o a functional spec is not likely to be accepted at proposal stage. – quickly_now Jan 13 '14 at 23:54
5

There's three things to keep in mind

1) You have to start somewhere

Have you identified what the problem this project is trying to solve is? You also could start by saying "Here are the things this project would not be complete if it couldn't do." I have also seen some projects (some successful, others not so much) design the main screen and fill in the blanks from there.

2) You have to end somewhere

You can spec things to hell, but if you never actually do anything all you've done is wasted a bunch of time and paper and ignored your wife and kids for seven weeks. (Been there done that, anyone?) So make sure to set some limits about how far your spec is going to go. Is it a technical spec as well as a functional spec?

3) You have to get from start to finish

Don't start by getting one major requirement and then filling in the every detail about it before getting the second major requirement at least in the outline. Build your spec horizontally first, then vertically. Otherwise, when you realize some minor detail of requirement one makes all of requirement two impossible, you're going to have some major issues.

corsiKa
  • 1,084
  • 6
  • 13
3

I would split your list into three parts: the stuff users care about, the stuff programmers care about and the stuff managers care about. Let a programmer do their part and a manager do their part. The programmer will probably need to provide estimates for parts of the project to the manager and the manager to provide the budget constraints to the programmer (i.e. It cannot take more than X weeks). If everybody (customer, manager, programmer) agrees, then it is a green light and start the project. For the programmer, many people poo-poo specifications, sometimes rightly so. I would only spec the parts where two or more parties are communicating (e.g. client-server). For the rest, just practice some form of TDD based on user stories. A line to the customer is also beneficial to get stories. Remember that the customer may or may not know what they want, so the user stories should be captured and saved for re-interpretation by the programmer.

User Stories

  • Purpose Goals Functional Overview
  • Actors (Data Sources, System Actors)
  • Use Case Diagram
  • Process Flow Diagram
  • Activity Diagram
  • Context Diagram
  • Business Rules
  • Special Requirements
  • Performance Requirements

Manager

  • Critical Project Success Factors
  • Expected Expenses
  • Flow Scenarios (Success, alternate…)
  • Time Schedule (Task Management)

Programmer

  • Security Requirements
  • Domain Model (Data model)
  • System Requirements

Also, there is probably not a perfect recipe for all types of software problems. For a Facebook app, you probably want to demo early and often. For a missile guidance system, probably not as much ;-)

2

Preparing all these documents may take months! Looks like a waterfall kind of approach to me.

I cannot suggest adding anything more to your list unless you take out a few from it. I guess the artefacts to be produced will depend on culture within your organisation, and skill set of the developers.

  • 1
    See my long answer. Waterfall is a silly approach IN ITS ENTIRETY because it assumes nothing goes wrong. (Gather requirements, specify, design, make, test, sell... ohh something went wrong... whoops, thats kinda tough). However the point about front-end-loading, where you do the requirement gathering and specification writing should not be ignored. Just because the whole process is naive does not mean you throw it all away. You look for the good parts and use them. – quickly_now Feb 20 '11 at 02:46
-1

There is no better functional specification that a working but fugly prototype, precisely because of the problems with a waterfall approach.

Job
  • 6,459
  • 3
  • 32
  • 54