RE: Bi-directional traceability and docs

[Rose -dot- Wilcox -at- aps -dot- com]

Dan writes:
"We're going thru the pains of CMMi here, and one of the objectives is
to institute "bi-directal traceability", which, in a nutshell, means
that the spec points to the places in the code and doc that need to
change to meet a user req, and the code and the doc reflect the user req
that prompted a change. And my group here has been asked to consider
implementing this traceability in our doc."

WHHHHOOOOA.  We're doing CMMI here too (BTW the legal spelling is with
the capital I) but we are only level 2.  What level are you
implementing?

In Level 2, traceability is defined as "the evidence of an association
between a requirement and its source requirement, its implementation,
and its verification."

"A little background. We release new software versions every 6 months,
each new version consisting of a number of user req "enhancements",
which are then summarized in Release Notes, and propogated throughout
the installation, configuration, and user doc. The Release Notes list
each "enhancement" that goes in a version, but the other docs do not
mention specific enhancements by number. The request is that the other
pieces of doc also begin mentioning the specific "enhancements"."

****

If you have need to communicate it to users, I would tend to confine it
to the Release Notes based on what you are saying.  Do you have user
acceptance testing?  If not, having the specific requirement in the
Release Notes can be helpful, but it sounds like you are already doing
so.

For business analysts, the need may be to trace specific requirements
for various reasons such as to determine they have been done (instead of
or in addition to user acceptance testing).  Beyond level 2, you might
want to track the requirements for metrics and so the business analysts
can find out which docs are affected by which type of requirements, how
much time such changes take, etc.  That's a higher level of CMMI than 2,
methinks.

To put the specific requirements numbers in the installation,
configuration, and user doc would confuse the reader and not really help
the business analysts in their job.  For the first need (to determine
they have been done) you are either going to use test plans and test
cases linked back to the specific requirements and/or the Release Notes.
For implementation, you probably need a work plan.  Linking the specific
requirements to your work plan will put you good stead for future
collection of metrics, provide the BAs with the knowledge of which work
products had to be changed per requirements, and maybe even help out the
doc department in planning.  

Disclaimer: We are doing CMMI Level 2 and there is no talk here of
putting Requirements traceability into user docs, so I have no actual
experience with it.  But if faced with that idea, I would counter with a
plan similar to the one I have delineated above.

Rosie

Rose A. Wilcox
Center for Process Excellence, CHQ 8th Floor
602-250-3195
Rose -dot- Wilcox -at- aps -dot- com

Buffy: ... Okay, okay, what do we do? (realizes her paranoia) What are
we doing? Xander, you get me started! We are totally overreacting!
Xander: But it's fun, isn't it?
"I Robot, You Jane"


"MMS <apsc.com>" made the following annotations.
------------------------------------------------------------------------------
--- NOTICE ---
This message is for the designated recipient only and may contain confidential, privileged or proprietary information.  If you have received it in error, please notify the sender immediately and delete the original and any copy or printout.  Unintended recipients are prohibited from making any other use of this e-mail.  Although we have taken reasonable precautions to ensure no viruses are present in this e-mail, we accept no liability for any loss or damage arising from the use of this e-mail or attachments, or for any delay or errors or omissions in the contents which result from e-mail transmission.

==============================================================================


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

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo

COMPONENTONE DOC-TO-HELP 7 PROFESSIONAL:  From a single set of Word documents, create online Help and printed documentation.  New version offers yearly subscription service, Natural Search, Modular TOC Utility, Image Map Editor, Theme Designer, Context String Editor, plus more. http://www.componentone.com/doctohelp .

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.