The Old Joel on Software Forum: Part 4 (of 5) - Great real functional spec examples

Great real functional spec examples

The sample spec with the "Painless Functional Specifications" series of article is nice. But it's short, simple and, well, made up. There's a tremendous difference between that basic five page spec and the 500 page VBA spec Joel speaks of later in the series. There's also a big difference between the real world functional specs I've worked with and the ideal that Joel is championing.

So, where might I find a substantial, real and *well-written* functional spec? I don't expect that most companies are eager to share such internal documents (I know my employers never have been), but in all the world someone must have published a good one. Right?

Sean Harding
Monday, May 17, 2004

Just a few more quick questions.

1. Should a spec be written like, The user "will" do this and that OR The user "does" this and that OR The user "can" do this and that?

2. What should I call the software in the specs? Software? System? or just call by its name (or code-name)?

3. Can I discuss the user interface? Like using Visio to create quick mock ups of what the user interface will look like?

Green Pajamas
Tuesday, May 18, 2004

Sean,

I can't unfortunately provide you with an example of functional specification.

I have found a lot of confusion with document titles between team members. I try to avoid the term "Functional Spec" and either call it a "Functional Requirements Spec" or a "Functional Description Spec". It also matters at what level the engineer it working at. One mans system is another mans sub-system.

The main aspect that should be borne in mind with any type of specification document is that it should be appropriate for the job in hand and contain enough information to convey what the reader needs to do his, or her job. This may sound obvious but you wouldn't believe how many people I have seen spending weeks polishing a document because some diagrams don't quite line up etc.

Although not examples, some esa software information can be found here....

http://styx.esrin.esa.it/premfire/Docs/

Green Pajamas,

Question 1...from the esa standards

“Sentences containing the word ‘shall’ are mandatory practices. These practices must be followed, without exception, in all software projects.

The word ‘must’ is used in statements that repeat a mandatory practice.

Sentences containing the word ‘should’ are strongly
recommended practices. A justification to the appropriate level in the Agency’s hierarchy is needed if they are not followed.

Sentences containing the word ‘may’ are guidelines. No
justification is required if they are not followed.
“

Question 2
Depends what the document is trying to describe. The terminology should be appropriate so that both the author and reader have a common understanding.

Ian H.

Ian H.
Tuesday, May 18, 2004

Oups missed one...

3. Can I discuss the user interface? Like using Visio to create quick mock ups of what the user interface will look like?

So long as it provides the author and the reader with a common understanding of either 1) what is required, or 2) what will be delivered, then it is good enough. If you are using it to illustrate the interaction between various forms then it might not be adequate? It all depend what you are trying to show/prove.

Ian H.

Ian H.
Tuesday, May 18, 2004

Another small example, but better than nothing? - http://www.mojofat.com/tutorial/index.html

Ben R
Tuesday, May 18, 2004

http://www.google.com/search?hl=en&ie=UTF-8&q=Functional+Specification+sample

The first page of results seems to have quite a few promising samples. It even has Joel's sample.

Steve Jones (UK)
Tuesday, May 18, 2004

This is a bit off topic but I've discovered that writing functional/ requirements specs is very hard if I haven't first made some mockups to visualize what I'm trying to do. Reading Joel's article gives me the feeling that he designs an application by writing a spec. That just doesn't work for me. Here are some mockups (in swedish) for a publishing system I'm implementing. They are Google and Typepad ripoffs but they have been very helpful in reaching a common view of the project:

http://www.grapestar.com/publicering/03google.gif

http://www.grapestar.com/publicering/04projekt.gif

http://www.grapestar.com/publicering/05projekt.gif

http://www.grapestar.com/publicering/06ikea.gif

http://www.grapestar.com/publicering/08hg1a.gif

http://www.grapestar.com/publicering/09fgym.gif

http://www.grapestar.com/publicering/10skriv.gif

http://www.grapestar.com/publicering/11nyheter.gif

http://www.grapestar.com/publicering/12nyheter.gif

Rikard Linde
Tuesday, May 18, 2004

Rikard

You said you could writing a spec doesn't work for you, but looking at the mock-ups that's exactly what you've got. It's just not in written text format. You said it was helpful reaching a common view, that's essentially the purpose of a requirements spec.

Ian

Ian H.
Wednesday, May 19, 2004

You're right Ian. What I meant to say was that I prefer to write my specs visually. I find it's easier to discover problems, glitches, differing views and more when everyone involved has something visual to talk about.
In the second stage I write a spec (text) with ALL functionality mentioned and described. Usually the visuals only serve as a reference to the text specs, something we refer to to clarify what we mean.

Rikard Linde
Wednesday, May 19, 2004