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: Tue, 15 May 2001 22:39:00 -0700

On Mon, 14 May 2001 19:04:51 -0700 (PDT) Andrew Plato <intrepid_es -at- yahoo -dot- com> opined, without sarcasm! from the sound of it:

... While many places have the engineers write the specs, personally I think
writers should. It forces you to get "down and dirty" with the technology
you are documenting. Moreover, you can become an intermediary between
competing ideas and concepts. Engineers often forget that their designs
must integrate with a whole. Having a writer develop the specs helps
reduce incongruous ideas and designs in the spec.
...Most engineers are horrible writers producing incomplete
specs. Mostly, what they do is write in a vacuum. They don't document
their designs in context. That is, they spec out designs without
explaining the rationale and reasons behind their decisions.
...Write the specs and have fun.

We must be nearing the End Time. I find myself entirely in agreement with Andrew Plato.

The only thing I wanted to add is: Don't be intimidated; feel free to ask questions. Many times, the "design" that an engineer proposes has gaps, inconsistencies, makes assumptions about information that will be available that actually WON'T be available, etc. You, as an outsider, are in a position of strength. You can't make the assumptions many engineers make and therefore you are uniquely in a position to question those assumptions.

The way I write a spec is to iterate. I interview the engineer(s) responsible. I organize and write stuff down, very clearly labeling my first result a preliminary draft. I run it by the folks who seem least likely to react defensively to what I've written. I beg for feedback and I incorporate that feedback into a subsequent version. Then, I run it by an expanded audience until most people agree that it's True. I ALWAYS have fun when I write specs. I hope you do too.


~ 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.

Previous by Author: Re: "Persist" as a transitive verb? <gack!>
Next by Author: Re: writing functional specs?
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