Fog Creek Software
Discussion Board

Who writes functional specs

Joel, I just read through your functinal specs (FS) articles. I think you have done a fantastic job on writing the articles. It really sheds some light on how to approach a FS.

One thing I would like to ask you. According to you, you did a 500 page on VBA strategy on excel, I feel this is simply amazing. I cant imagine myself writing a 500 page of anything.

How long did you take to write the 500 page?

You mentioned that there should be a  program manager who writes a functional spec. IT landscape has been tougher and tougher. As a new IT profesional I found that, most company strategy to cut cost, is first by minimizing the number of people in one project. As a result the project manager actually delegates the spec to the developers. And I am starting to see your point on " Dont let developer write Functional Spec". The FS is simply a disaster. Furthermore new developers find it difficult to code the module by reading the FS alone.

Well im not being lazy or anything, but for me I feel it is a little bit ineffecient to have one project manager to write all the specs. So ideally we sohuld have some project managers to oversees some specs. But with the tight budget it impossible to hire to many project managers.

Lastly,forgive me for ovewriting this, has anyone have this kind of problem? Then how do you guys tackle this problem?

Irfandhy Franciscus
Saturday, April 17, 2004

The spec took several months, at least, I don't remember exactly.

I think the right ratio of program managers to developers is about 1 to 5. More than that and the developers can't keep up. Less than that and the program managers can't keep up. In otherwords, one full time software designer can write enough specs to keep about 5 full time developers working.

I used to think that delegating specs to developers was the right thing to do if you just can't get management approval for a dedicated program manager. I have since changed my mind on this one... you really need a dedicated person to this; developers don't necessarily have the right skill set, and it's a little bit like asking school kids to write the questions for the test as well as the answers.

Joel Spolsky
Fog Creek Software
Monday, April 19, 2004

What if you have, say, 2 or 3 programmers in a particular group - in that case is the best strategy to have the most senior programmer write the functional spec?

Kevin Clary
Monday, April 19, 2004

I'd rather give them a 1/2 time program manager who also program manages another small group.

In any case I wouldn't give the "senior programmer" the benefit of the doubt... I would look for the person most likely to be user-empathetic and to show good business judgement.

Joel Spolsky
Fog Creek Software
Monday, April 19, 2004

Just a general comment on functional specs. On them I respectfully (and unusually) disagree with Joel.

If you look at how Joel writes his specs he essentially lays out the different user interface states, and describes the detailed behavior of each.

It is my opinion that this is putting the cart before the horse. I would not call this a functional spec at all, it is a design of the user interface. The purpose of a functional spec is to capture the requirements that drive the need for the software.

A functional spec should contain the WHAT of the software, not the HOW. Joel's specs represent HOW the functionality is implemented and presented to the user. This is part of the design of the software, it is not part of the requirements gathering and specification.

Let me give you an example. If I were specifying, say, an application to manage web content. For the editor I might say, in a requirements document:

The editor will allow the user to make some text bold, italic or underlined.
The editor will allow the user to choose from the standard HTML defined fonts.
The editor will allow the user to enter text.

And so forth. These are the actual requirements. There are many different ways to implement these in a user interface, (a bold button, a bold menu item, a context menu, and so forth) and of course a good user interface design would probably include several ways of bolding text.

I am not saying that Joel's spec is bad, on the contrary, I think it is excellent, it is just not a requirements spec, it is a GUI design spec. This is an important engineering document, however, how do you know what to put in that document?

The answer, in my opinion, is that there is a requirements document that preceeds this document. This document is the fundamental basis for all subsequent work. It is a point by point list of WHAT the software will do, specifically not discussing how it will be done.

Focusing on the how is distracting to the point of loosing sight of the goal of the software.

Jessica Boxer
Monday, April 19, 2004

I would say that what you have just described is a requirements document, which I would put down as being quite seperate from a functional spec. The requirements doc would, in my mind, come either just after, or partially during, any domain analysis you're doing, which should be after your initial design and briefing... My opinion only of course, there are no rules for software engineering...

Andrew Cherry
Tuesday, April 20, 2004

I run into disagreements about this all the time at my job.

There are several needs to be satisfied by documentation in order to produce a system.  One need is, "What will the system look like to the user?  How will it work?  What will it do for them?  What value will it provide them?"

This need is satisfied by what Joel calls the Specification.

Another need is, "What functionality must the system have in it?  How do we know when we're done?  What contractually are we held to deliver?" 

This need is (should be) satisfied by the Requirements Document.  Requirements must be testable, verifiable, and measurable.  Much of what is in the Specification is very 'fuzzy' in terms of requirements -- but is very important in terms of understanding the purpose and operation behind the requirements. 

The Requirements can often be very 'detailed' -- like your 'Bold' example above -- but without the Spec, knowing WHY the user would NEED to make something 'Bold' is left unsaid.  This can lead to building systems that meet the requirements, but don't meet the need. 

Tuesday, April 20, 2004

Without getting caught up in the semantics of "what makes up a functional spec" I would have to say that the purpose of the Functional Spec is to tell the developers exactly what they are supposed to be developing. The particular example that Joel made was heavy in the UI department because it is a customer facing website whose functions tie directly into navigating web pages. If you were writing a spec for a service, the spec wouldn't be have any UI. Just listing the requirements is not a spec, and if you were to give a developer a PRD then you would likely not get back what you were expecting.

No Name
Tuesday, April 20, 2004

Specifications are not necessary at a small company in which every coder is good.
I know this because i've worked at one. We came out with a product which sold
well and propelled us to success. We did not write specifications. We worked
together in a small building. When we had issues or questions, we walked over to
whoever-it-was' office and discussed them. When the CEO (also a programmer,
although he did not assume that role at our company) wanted things done a
certain way, he told us and we did it that way. Usually, he was right, although we
did not always discover this immediately.

Probably, specifications are needed at a larger company such as Microsoft.
I agree with you that humor is useful when writing a specification. If it's not used,
the specification may wind up boring and no-one will read it, as you have stated.

Nonetheless, the assertion that written specifications are necessary in order to
produce good software is false, because there is a counterexample.

Justin R. Bendich
Friday, April 30, 2004

*  Recent Topics

*  Fog Creek Home