Re: writing functional specs?

Subject: Re: writing functional specs?
From: Berk/Devlin <armadill -at- earthlink -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 16 May 2001 08:38:37 -0700

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.


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

I think the conversation has drifted off target. The original post was about writing functional specs (aka requirements specs, not design. If you're interviewing SMEs about a "design," you aren't talking about functional/requirements'd better be interviewing customers.

Your description about how you work with an engineer(s) who "proposes a design" (assuming you're talking about design specs) sounds more like an SOP for any document. Specs are different animals. The design spec is a daughter document of the functional/requirement spec, and should be reviewed against the criteria in that document that the internal/external customer has signed off to. Ideally, those folks you have reviewing the design spec were also involved in the development of the functional/requirements spec, as well as those responsible for implementing the design.

If you really want to have fun with specs, try getting on the team that develops the functional/requirements spec and stay with them through the design spec/document, architectural spec, statement of work or product implementation plan...

~ Emily Berk ~
On the web at *** Armadillo Associates, Inc. ~
~ Project management, developer relations and ~
extremely-technical technical documentation that developers find useful.~


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See or 800-463-6627 for more about our solutions.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Re: writing functional specs?: From: Lurker writer

Previous by Author: Re: writing functional specs?
Next by Author: Eating Your Own Dog Food Was: Interviewing Subject Matter Experts
Previous by Thread: Re: writing functional specs?
Next by Thread: Re: writing functional specs?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads