Re: writing functional specs?

[Berk/Devlin <armadill -at- earthlink -dot- net>]

Hey Lurker:

I consider a functional spec to be a contract between various 
constituencies within a company -- in particular, the engineers, marketing 
and qa.  It is the bird's eye description of how a product works and it 
lists what the product is to do.

Therefore, in my opinion, within the functional spec, the writer has to 
"prove" that what is being proposed in the functional spec is technically 
feasible and usually within a particular very short time frame.  And that's 
where, in my opinion, design must come in.

If you only talk with end-users when developing a functional spec, what you 
end up with is a marketing document.  You must then take that list of 
demands (which is all you have at that point), hat in hand, to your 
engineers, and ask them nicely if they could possibly see their way clear 
to implementing it.  I've seen documents like these handed to engineers, 
and in general, the answer an engineer will give is, "Why, yes, I can 
implement this.  Right after I finish the project I've been working on for 
the last twenty years, which is a mental-telepathy machine."  (But 
sometimes they are not quite as polite as all that.)

In other words, yes, you talk with marketing, maybe end-users, etc. about 
what they WANT and what they think they need/want.  THEN you talk with the 
engineers about what's possible (and what ELSE is needed).  Otherwise, what 
you end up with is useless.

Also, in my experience, specs is specs.  In many places, you only get to 
write one spec.  Over time, the functional spec/requirements spec becomes 
the technical requirements spec becomes the technical architecture document 
becomes the enterprise architecture document (if the company lasts long 
enough).  I'm sure this is not the way it works in all companies.  But at 
smaller, early-in-the-corporate lifecycle places, and, even at some places 
where maybe they should know much better, the earlier spec becomes the 
subsequent spec if there is even a spec at all.

And, very often, in my experience, the "specs" are often written after at 
least one release exists or because a potential source of funding wants to 
see one about the existing product.  So the design percolates in because 
the "functional" spec "rationalizes" (in multiple senses of that word) what 
already exists and explains how the functionality will change over 
time.  Which again means that the features listed are defined well enough 
in the spec so that an engineer understands how the spec writing team 
intended them to be implemented.  Otherwise, you do not get engineers 
buying in to the spec and it languishes on marketing's desks.

Anyway, I think it's more fun when you DO talk with the engineers.  Guess 
that's why I'm in the particular niche I'm in.

--Emily

At 07:06 AM 5/16/01 -0500, Lurker writer wrote: