writing functional specs?

["Burt, Genevieve" <GBurt -at- lrs -dot- com>]

I second Andrew.  

Writing functional specs has been part of my career activities since day 1
as a tech writer.  At first, it was an uncomfortable experience because the
technology, terms, concepts were new to me.  But the more questions I asked
and the more specs I wrote, the easier it gots and the better I got at it (I
am now able to produce specs faster, in more detail, and with less
butterflies).  

As Andrew pointed out, technical writers, once they grasp the goal of the
project and understand the technologies being used, do a much better job of
writing specs than most techies.  Plus, it gives us an "in" on the
project--it's the best way to become part of the project team!

I should mention that writing functional specs for hardware is somewhat
different than writing specs for software.  Writing specs for software
requires more business analysis skills, while writing specs for hardware
calls for more scientific/ mathematical skills.  But both can call for a
background in statistics, because functional specs usually include estimates
and parameters (such as 'worst-case' transaction load, for web servers).
Techwriters don't usually have to come up with the numbers, but it is
helpful if they know what statistics to ask for and how to double-check
them.

There aren't many good examples of functional specifications on the web
(that I have found, at least), and it's a type of documentation that wasn't
taught to me in TechWriting 101.  I picked up the skills to write them OTJ,
from some good project managers.  Each project will demand different kinds
of content, and each project manager will finesse the spec with his or her
own style, but a general outline of a functional spec looks like this:

1 Introduction	
	1.1 Project Background	
	1.2 Business Need	
	1.3 Project Goal	
	1.4 Terms Used in this Document	

2 Process Overview
	2.1 Process Flow	
	2.2 Conceptual Data Models	
	 
3 Overview of Use Case Modeling	
	3.1 Overview	
		3.1.1	Use Cases 
		3.1.2	Scenarios 
		3.1.3	Actors	 
	3.2 Actor Catalog 
	3.3 Use Case Diagram	

4 Use Cases 
	
8 Requirements	
	8.1 Operational	
		8.1.1	Connectivity	
		8.1.2	Data Storage	
		8.1.3	Transactional Flow	
		8.1.4	Turnaround/ Response Time	
		8.1.5	User Interface	
		8.1.6	Security	
		8.1.8	Data Management Audit Trail	
	8.2 Training	
		8.2.1	User Manual	
	8.3 Material	
		8.3.1	Network Infrastructure	
		8.3.2	Hardware	
		8.3.3	Software	
		8.3.4	Fault-Tolerance	
9 Appendix	
	9.1 Submitted To	
	9.2 Approvals	
	9.3 About this Document	

This is a basic outline I use for specing software projects (web
applications).  I use UML diagramming (Actor Catalogs and Use Cases) to help
me specify the business requirements/ process flow of the systems.  Diagrams
are an essential part of functional specs for two reasons:  it helps you
make sure you've got a grasp on the big picture and how the pieces connect,
plus it gives VPs quick and easy access to the information in the document.
We turn in the functional specification, along with the software prototype
(done in HTML) to the decision makers for sign off prior to project kickoff.

Hope this helps!
--Genevieve

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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