Writing Requirements Documents/Functional Specifications, etc.

[Lyn Worthen <Lyn -dot- Worthen -at- caselle -dot- com>]

Kathleen, Karen - 

(Copying this to two lists, as the topic seems to be relevant to members of
both groups)

Our development team has decided that they need to have a writer in all
design/development meetings.  What started out as a glorified role as "note
taker" for these meetings has grown into my having a major role in the
creation of both the Design Document (developed with the original design
group - sales/support/training staff) and the Preliminary Functional
Specifications (working with the extended design group, adding developers to
take the "what we want" aspect of the Design Document, to move it to a "what
we can do" from a programming end, and create first draft UI designs).  The
final Functional Specifications document that the developers actually create
the product from will probably be written by the product manager, over in
the development dept, who has been a participant in the current design
meetings.

In addition to Donn's article (mentioned below), which I found very useful,
the Techwr-L archive also contains a very good "definition of a functional
spec" - part of an email discussion on the listserv, posted by Steven J.
Owens.  He made some very useful comments about the role of the FS in the
development process (take particular note of the 3rd-4th pages of his post).

Two books on the topic that I've found to be useful are:

 - "Requirements by Collaboration," by Ellen Gottesdiener (ISBN
0-201-78606-0)
   A useful guide for working with a team to create your requirements
documents; particularly useful if your design teams aren't used to working
in a collaborative mode, and are wasting numerous hours in meetings that
never seem to get anywhere or result in any specific decisions.

 - "Software Requirements - Styles and Techniques," by Soren Lauesen (ISBN
0-201-74570-4)
   He presents various types of requirements (not all for IT-situations, but
still applicable), and approaches to creating them.  It's written in a very
informal style, but is a very thorough treatment of the subject.

(As an aside, I got both books from www.nerdbooks.com, and was very happy
with their service!)

 - A good website, with a wealth of resources I haven't begun to fully
explore, is www.stickyminds.com.

One thing I found in my research of specs and templates for such, is that
there appear to be no hard and fast rules for writing them.  Look at the
specs your developers have created/used in the past, and research how
well/poorly those worked for them.  Some groups thrive on paragraph
numbering, others despise it; some groups want very formal language, others
work better with a more casual tone/presentation.

Most of all, keep in mind that these are "living documents" that will
continue to be modified through the development lifecycle.  They will go
through many iterations - possibly changing names a few times as you go --
our Design Requirements Document became the basis for our Preliminary
Functional Spec when we moved into that phase of the lifecycle, and will
likely prove to be the foundation for both the final Functional Spec as well
as for the initial draft of the product documentation.  It's a great way for
you as a writer to be involved in the product design from the ground up.

best of luck,

Lyn


-----Original Message-----
From: LeVie, Donald S
Sent: Monday, April 21, 2003 6:06 AM

Kathleen:

If I can humbly recommend my article on "Developing Software
Requirements Specifications" at the TECHWR_L web site...you'll find my
recommendations for including tech writers on the requirements-gathering
team as well as the spec development team.

Donn LeVie, Jr.
Personal Client Architecture Components Group (PCG)
Applications Engineering/Technical Publications
Intel Corporation
(512) 314-0221
donald -dot- s -dot- levie -at- intel -dot- com


-----Original Message-----
From: Kathleen Bauman [mailto:kathleen_bauman -at- idx -dot- com] 
Sent: Friday, April 18, 2003 4:06 PM
To: STC Management SIG discussions
Subject: [stcmgmtpic-l] Documenting from requirements

Hi everyone. I'm a fairly new documentation manager dealing with a
complete reworking of our software development processes. One of the new
visions is to have the Doc group write concurrently with Engineering
without the traditional lag time after coding has finished. The
documentation is then tested against the code while the code is also
being
tested.

The organization does understand that to do this, we need to have very
clear requirements. Currently, we're not at that point, but to help get
us
there, we've recognized that we need to involve the writers early on in
the development cycle and help with the requirements (including UI
specs).
We are struggling with this mostly because our cycles overlap and while
the next release is elaborating, we are in crunch time wrapping up the
previous release's doc.

We've also discussed the importance of change management. Too many times
there will be a conversation in the hall and the engineer will
completely
rework the functionality, much to the despair of the writer who just
happens across the change in the application.

I'm wondering if anyone has seen or experienced this model working. If
so,
do you have any suggestions for making it work and for avoiding any
common
pitfalls.

Thanks!
Kathleen

---
You are currently subscribed to the STC Management SIG List as:
donald -dot- s -dot- levie -at- intel -dot- com -dot-   To make changes in your subscription via the
web, or to search the list archives, browse to
http://lists.stc.org/cgi-bin/lyris.pl?enter=stcmgmtpic-l
To unsubscribe send a blank email to
leave-stcmgmtpic-l-119465O -at- lists -dot- stc -dot- org

---
You are currently subscribed to the STC Management SIG List as:
lyn -dot- worthen -at- caselle -dot- com -dot-   To make changes in your subscription via the web,
or to search the list archives, browse to
http://lists.stc.org/cgi-bin/lyris.pl?enter=stcmgmtpic-l
To unsubscribe send a blank email to
leave-stcmgmtpic-l-119465O -at- lists -dot- stc -dot- org

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Last chance to order RoboHelp X3 and receive a $100 mail-in rebate, 
PLUS free RoboScreenCapture and WebHelp Merge Module. Offer expires 
4/30/03! Order here: http://www.ehelp.com/techwr-l

   Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

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