Re: Requirements/Specifications

[Andrew Plato <aplato -at- EASYSTREET -dot- COM>]

I've written a ton of specs.  Well, maybe only 1500 or 1600 pounds worth.
But that is still a lot of specs.

Here's what I put in them:


Premises:  This is the most important section of a spec.  It states all the
things you expect the reader to know.  It also states all the requirements
for the product such as "this product will be compatible with Windows NT,
Windows 95, and Windows 98..."  etc.  It also discusses (and that is the
operative word) technical concepts that are important to the product.  For
example, if you are designing a tool that will gather and display data from
the logs on an IIS server, you must first talk about what those logs are,
the information in them, and why you are gathering information from those
logs.  This technical information is critical to understanding the
successful operation of the system.  Remember to draw the line somewhere at
what you consider "fundamental" knowledge you expect the reader to possess.
Remember, a spec is not for the general world.  It is for a fairly technical
audience.  You should not need to provide detailed explanations about the
fundamental technologies used for the product.  Merely how those fundamental
technologies will be exploited for the product.

System Flow:  For complex applications or products with a data or processing
flow, it is extremely important to do a big-old flow chart that shows what
goes where.  It is a horrible, time consuming task but it can turn a
useless, ignored spec into a fantastic source of reference.

Design Guidelines:  List of guidelines to use for designing and coding the
product.  Typically, this is where you would discussion common look and feel
shit.  Also any coding requirements.

Design Specs:  IF it is a GUI application, shoot each prototype screen and
spec EVERY SINGLE object on the screen.  Be very thorough.  Emphasize the
relationships between objects on the screen and actions in the system.
Remember to map all objects to what they do and where they take the user.
If a database is involved, map each data field to the database table and
column. If it is not a GUI app or you have no prototype, describe each
section, component, or object in the product.  Again, focus on the
inter-relationships between system objects, screens, or components.  Those
relationships are ultimately what form the architecture of the product and
they are ultimately what drive the engineering efforts.

Database Dictionary:  Typically the database designer will do this and the
tech writer merely incorporates it into the spec.   It is a VITAL element in
a good spec if your product uses as database.  A good data dictionary
includes a DETAILED copy book describing each table, each field, each
relationship, and all stored procedures.  An ER diagram should be included.
This helps graphically show the relationships between the database
structures.  If there are stored procs or triggers, document what each one
is, how it is triggered, what it does, and why it is used.

Glossary:  Define all terms and acronyms used in the spec.



That's it.  It is very important to focus 100% on communicating things as
easily and with as much detail as possible.  A good spec is painfully
detailed and thorough.  Since most people only read portions of the spec, it
is not terribly important to write everything perfectly and using a
fantastic template.  Just slap the shit on a page and force it to make
sense.

Audience analysis for a spec should take you 23 1/2 seconds.  Ask your boss
"who will read this."  Use his answer as your audience analysis.  Done.

In my experience, a good spec is a community effort.  The engineers, QA
staff, database admins, and marketing folks all work together with you.  As
the writer, you should become a "drain" where all information filters down.
You should keep your opinions in your pants and follow the lead of the
people designing the system.  Nothing frustrates engineers and programmers
more than a tech writer who thinks he is a programmer.  I have worked with
lots of other writers who take spec writing as their cue to lead.  This
typically irritates many egos and in the end kills the effort.

The fun of writing a spec is letting the programmers, database admins,
marketing folks, etc. lead it.  If you just document their work and take
things very literally, you can ultimately demonstrate the holes in the
system without every saying a word.  If they say the product will operate at
120,000 degrees Kelvin, put it in the spec in huge black letters.  When they
read it and leap out of their skin, you can say "hey, you said that's how it
would work.  Who am I to question that?"  It is a moment where you can rise
above the crap and look very professional.  Naturally, they'll tell you to
change it.  But, without saying anything, you just demonstrated a hole in
the system through good technical communication.

The best part of writing specs is that if your write them well, the company
will make a good product and your efforts will get noticed.  Specs are, in
my opinion, one area where tech writing is at it's truest form.  It is one
effort where you can really make a direct impact on the product and the
company.  However, if you write a bad spec, people will ignore you.

Good luck.

........................................................
Andrew Plato
Owner/Principal Consultant
Anitian Technology Services
www.anitian.com

(PS: The text contained within this message is mostly opinions, not facts.
Taking offense at opinions is a natural part of being human. If you feel
compelled to howl at how unfair the universe is based on my opinions, please
direct your complaints to billc -at- whitehouse -dot- gov, last I heard he can "feel
your pain."  Thank you and have a nice day.)