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.
Subject:Re: Using functional specifications as help From:Gurudutt Kamath <guruk -at- GIASBM01 -dot- VSNL -dot- NET -dot- IN> Date:Fri, 20 Feb 1998 10:02:11 -0600
Barbara,
I have two recent experiences to share. I did two projects for a company
where they gave me the Functional Specifications and I was to write the
User Manuals for them. My task was very easy because the Functional
Specifications (FS) were written as if they were user manuals. "The
Inventory Module will maintain inventory by length, volume, blah, blah,
blah, etc." Interestingly, the Company told me: "Guru, don't make it
sound/look like the Functional Specs." A tall order, as what they had
written was really a User Manual disguised as FS.
I have seen this scenario several times. (If your FSs are like that, then
converting them to Help would be an easy task.) However, I've seen the
opposite scenario too where FS really meant laying down the specifications
of the system. What the system is expected to do and what are the
approaches to achieving them. In which case, the FS can serve only as a
reference.
To quote a fellow TEHCWRLer, documentation is like changing tyres on a
moving truck. I did a project in Hong Kong, where I was given a 3,000 page
functional specs and told -- go through this -- but the system today has
totally changed. This is the reality. FSs are no more than "plans". The
final implementation may bear large, little or no resemblance to the system
delivered. The usual scenario is to synchronise the User Manual with the
system and then go back and re-write the FS to match today's reality.
In sum, you need to have a good look at the delivered (ready) system and
the FS. Check the language ("is it too technical?"), tone, concepts being
communicated in the FS and then convert it to Help as appropriate.
The usual route I take is: Use all system docs (Proposals, Requirement
Specs, Functional Specs, Design Specs, Program Specs, etc) and then write
my User Manual. From the User Manual to the Help File is one hop, step,
and jump. Of course, one could try the reverse also, Help first and then
the User Manual.
Your Query
==========
Our company develops broadcasting software and I write the online help
for the software. There has been some debate at our company as to whether
or not our clients can use functional specifications to help them use our
software. I guess this would be a replacement for the online help we are
currently writing. My feeling is that functional specs are too technical
for clients and they do not tell the clients how to do the things they
need to do. I was wondering if anyone out there has had any experience
with this.
