Fog Creek Software
Discussion Board




Starting a Functional Spec Late

I work on a product that has been around for a couple of years, but has never had a functional spec. We've encountered virtually all the problems Joel outlines in his "Why bother?" section -- and then some. There's a growing desire to do more planning before development starts, but convincing management to invest time in creating a complete and detail functional spec is a hard sell.

The current approach is to write short descriptions of features that are new or changed since the last version. Those descriptions are then handed to developers.

When I suggest creating a functional spec, I get the following reaction: Why bother documenting features that are already in the product and work?

Is it worth starting a complete and detailed functional spec for a product that has already shipped a few versions, or is most of a fuctional spec's value realized in the first version?

Jeremy
Monday, September 30, 2002

easier to train new engineers
easier to go back and fix bugs
easier to go back and change features
easier to go back do branding (change logos, company name)
easier to forecast additional development

daniel shchyokin
Monday, September 30, 2002

Less disputes between testing, development and PM, about what is a bug!

daniel shchyokin
Monday, September 30, 2002

I'd be against the func spec. Firstly, I personally would find it extremely painful to write, and I've never believed in retro fitting doco as it defeats the whole point of the doco, which is to facilitate development, not the otherway around. When you document new features or changes, I would go over the top with the doco then, trying to describe the changes in more detail than you would if there was a func spec. In this way at least you can build up some doco rather than trying to write from scratch.

Alberto
Monday, September 30, 2002

this assumes you have a good memory and work on only a few apps OR you put a lot of comments in the code (in which case it shouldn't be that painful to write a spec)

Also, if youre company is hiring, writing a spec will keep you from getting eaten alive by new hires

Daniel Shchyokin
Monday, September 30, 2002

Alberto,

Development doesn't stop once the product is ready and released. Maintenance, more than anything, lives or dies by the quality of the documentation. Both functional and technical.
How would you fix a bug when there is no documentation to tell you what the appropriate behaviour should have been?

Erik
Tuesday, October 01, 2002

Easy,

If the previous version dosn't have the problem, it's a bug and you know the correct behaviour.

If the previous version does have the problem, it's a feature ;-)

Robert Chevallier
Tuesday, October 01, 2002

Documentation is entirely about what is, not about what should be.

So, a functional spec after the fact is fine.  More than fine its a good foundation.

A functional requirements document is a different animal.  Its there to be negotiated about and then (in my terms) responded to with a development specification.  However that specification does not document the application, it documents the development process.

When you come to ship, you'll have a product which intersects closely with the development spec but not absolutely, there will be some shrinkage here, some creep there.

Then if your documentation systems are good you can roll out an accurate functional specification.

I'd be quite surprised though.

Simon P. Lucy
Tuesday, October 01, 2002

Simon,

The rest of your reasoning seems to contradict your own first sentence, so I am not sure what your aiming at. I would phrase it like this. I think you would agree.

Documentation is both, only not at the same time.
At the begin of a development, during preparation, documentation tells you what should be. First functionally, than technically.
At the end of the project the documentation has become what is. Either because you built everything according to plan, or because you adjusted the plan to build it differently.

However, there are always idiosynchrasies where the product turns out not to behave as documented after all. Which is a bug, be it accidental or intentional. The documentation becomes your reference of how it should have been. You then decide to adjust the product, or the documentation.

Erik
Tuesday, October 01, 2002

Hmmm.  I'll admit to not being clear but no I meant what I said.

Documentation is for what is.  The negotiation of what is wanted in some future product is documented in the Requirements Document (mostly generated by Marketing or whatever passes for it).  That Requirement doesn't document the final product.

Engineering (or whatever its called), responds with the Development Specification often mis-named as a Functional Specification which is where the problem comes in.  It might be called Engineering's Response to Requirements Document #SCI129087 as well :-)

Whatever, that document again doesn't document the product, it documents the process and is contemporaneous with the process.  Its a dynamic document because it should record all of the change requests and junk that happens in the process.  In reality its a collection of documents, email and bug tracking.

Finally, you get the released product.  At this point it would be nice if someone fixed up all of the mess and produced a Functional Specification which described the Product.  But it rarely happens, everyone is too busy discarding the empty champagne bottles and fixing the bugs in shipped product.

The idea, the fact of the Product as it is, often resides in the heads of those involved in it, and its more likely to be in the heads of support engineers than developers.  The evidence for some functional behaviour will be 'somewhere' but its likely to be a story and not a simple '10.5 Treatment of negative integers in Price entry field.' kind of thing.

You can tell I'm supposed to be doing documentation today can't you?

Simon P. Lucy
Tuesday, October 01, 2002

"Documentation is for what is. The negotiation of what is wanted in some future product is documented in the Requirements Document <<snip>>."

This is where you confuse me. Your requirements document is also documentation.

So there are different types of documentation. The type that you create beforehand to document where you want to go, and the type that you create while going there, to show where you've been. In between there's the documentation you create to document how you are going to get where you intend to go.

There's a time and place for all of them. There are also ways to create them in such a fashion that they retain there usefulness even after the fact. For instance, your functional specification should be the basis for, or even be, the user documentation once the product is done. It might need some reorganisation, or at least reformatting.

Erik
Tuesday, October 01, 2002

It seems like the general feeling is that a functional spec would be good, even late. But how to justify it? From what I understand, there's no overwhelming reason to write a functional spec at any point, except that it makes everyone's life a little easier. For example, we shipped a few versions without one. Therefor a functional spec isn't strictly required.

Jeremy
Tuesday, October 01, 2002

easier to train new engineers-tell the boss how much to is spent on new hire's questions that could be replied "rtfm"


easier to go back and fix bugs- bring up all your recent escalations, and mention how much time could have been cut, had you remeberd...

easier to go back and change features- see above

easier to go back do branding (change logos, company name)- does your company have OEM sales channels?

easier to forecast additional development - what phb doesn't want that!

Daniel Shchyokin
Tuesday, October 01, 2002

"It seems like the general feeling is that a functional spec would be good, even late. But how to justify it? From what I understand, there's no overwhelming reason to write a functional spec at any point, except that it makes everyone's life a little easier. For example, we shipped a few versions without one. Therefor a functional spec isn't strictly required."

Jeremy,

It doesn't just make everyone's life a little easier. Unless your building trivial tools with one simple goal and a few in and outputs.

You may ship without a functional spec, but if the product is anything the customer expected, you have been lucky. Lucky to have someone who already knew what the customer wanter, lucky that your product was so simple, lucky to have so many smart people on the project, lucky that you never had to actually work with it, whatever.

But serious people don't bet there future on that kind of luck. Because it is too risky in the long run. Products get more complex, people get ill or leave. How will you continue to work together if you have no other means of communication than word of mouth, or maybe telepathy?
How will you explain to new workers how the product is supposed to work?
How will you divide work among colleagues?
How will you get approval to build anything if you can't show your customer what you are going to build?

These are but a few issues, but the should illustrate that it doesn't just make life a little easier, in many cases it enables what would otherwise be impossible.

And for some common sense, look before you leap...

Erik
Wednesday, October 02, 2002

Here's an alternative course of action:  Don't try to justify it; just start writing it at odd hours.  Don't spend significant time on it, but just hack away at it for ten minutes at a time when you're frustrated with your current tasks.

Then, when you have something to show, take it to your boss as a proof of how useful the functional spec would be.  Once people actually *see* the documentation, there's a better chance they'll understand its value.

You shouldn't need permission to do something that will improve the project.  Just make sure you don't sacrifice your core work.

Brent P. Newhall
Friday, October 04, 2002

*  Recent Topics

*  Fog Creek Home