TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Can anyone provide info as to how a TW writes a Software Functional Spec for
a GUI interface? What are the key elements the TW should know? What is the
document used for?
Tony Markatos responds:
The Software Functional Spec is an input to the software design process. It
tells the designers the essential tasks (functions) that the software must
accomplish.
The primary thing required to write clear, concise, comprehensive functional
specifications (GUI interface or not) is an understanding of:
* The purpose of the product. (Often this is not readily apparent.)
* The scope of the work area considered in developing the product. (Will
include both automated and manual tasks.)
And, within the scope, a rigorous understanding of:
* The end-user's goals and how all of those goals interrelate.
* The essential data relationships.
* The current tasks accomplished (both automated and manual) to achieve
each goal.
* The steps required to accomplish each task.
To get the above understandings, you need a copy of the following
(requirements analysis related) documentation:
* Data Flow Diagrams (or something similar to DFDs) - and supporting
text/logical flow-charts.
* Entity relationships diagrams (or something similar to ERDs).
* Optionally, Use Cases. (Use Cases are the current rage - especially
within the OOA community. However, I have found, OO or not, that I can
forego having to create such by making my DFD's highly slanted towards
typical scenarios.)
If you do not get the above from the folks "upstream" in the development
process (and most often you won't), you will have to create such yourself.
Once you obtain an understanding of the current tasks/steps, you change
them as necessary per the new automation. While end-user goals don't
change, tasks/steps do with new automation.
Per automated task, the functional requirements are simply a restatement of
the steps as requirements. For example, if one of the steps within a given
automated task will be "Calculate sales tax". Then the requirement is
written as: "The system shall be able to automatically calculate sales tax."
Next, for each functional requirement, you need to write a validation
criteria. For example, a validation criteria for the requirement "The
system shall be able to automatically calculate sales tax." would be
something like "The sales tax must be calculated to at least two decimal
places.". (Validation criteria are a primary input into testing.)
The above is a bare-bones approach to writing functional requirements specs.
Additional things like the risks associated to implementing each
requirement and the priority of each requirement may also need to be
documented.
Tony Markatos
(tonymar -at- hotmail -dot- com)
Discover the true meaning of life - always drive within posted speed limits.
A. Markatos
______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com
