Re: writing functional specs?
... 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~ Emily Berk ~
On the web at www.armadillosoft.com *** 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 http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com 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 http://www.raycomm.com/techwhirl/ 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?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads