How to Refer to Other Documents within your Requirement Document

Posted on: September 4th, 2012 by Lou Wheatcraft 2 Comments

We were recently asked the following question from one of our clients concerning how to refer to other documents within your requirement document:

One of my co-workers stated that just by listing a document in Section 2.0 “Documents” made all the requirements in that document fully applicable, in toto, to the system.  This seems dangerous, and unwise, to say the least. 

I have always maintained that only the ‘shall’ statements are requirements, and we use an applicability matrix to track those documents that are cited or invoked within shall statements, helping to control the versions that are specified.  I’d be very interested in seeing how the Requirements Experts addresses this topic.  I’m betting that this is a communication error….

Applicable vs Reference Documents: There was definitely a big misunderstanding.  We recommend that Section 2.0 of the system requirement document have two sections, “Applicable Documents” and “Reference Documents.”  Within these sections, it is common to see a further breakdown between internal documents, regulatory documents, and industry or international standards. These two tables list all the applicable and reference documents that are directly sited within the document. [In the old days, it was easy to cut and paste Section 2.0 of another requirement document into your requirement document.  Section 2.0 grew and grew and looked like a listing of the Library of Congress!  Documents were included that were never invoked by a requirement!!!]

Following the most used outline for system requirement documents, Section 3.0 contains the actual system requirements “shall statements”.  The requirements call out the document number and only the applicable sections of the document.  Section 2.0 contains the document number, title, revision, and date of the current revision.  Some organizations also include a fifth column listing the requirement numbers that call out a specific document.  [A primary reason for and use of Section 2.0 is to help your organization’s Configuration Management Office know which documents they need to track and which projects to notify whenever the CMO becomes aware of a change or pending change to one of these documents.]

Using this approach, an “Applicable Document” is one that is referenced directly by a requirement in Section 3.0.  A “Reference Document” is one that is referenced elsewhere within your requirement document, but not in a shall statement.  Thus reference documents are just that – a source of reference information but nothing is binding.  Reference documents are frequently referred to in sections other than Section 3.0 or in the requirement rationale.  The only portions of an Applicable Document that is binding (and will be verified) are the specific sections or requirements called out by your requirements.

We caution our students to never call out a complete document in a requirement unless every requirement in that document is applicable.  If not, then only call out the parts that are applicable.  These types of requirements need to be allocated to the next level of the architecture.

Applicability Matrices:  A good way to allocate requirements from the system level to subsystems to assemblies to subassemblies to components is via applicability matrices.  These matrices are often included as an appendix to your requirement document.  In the applicability matrix for a given applicable document, each section or each requirement is listed as a row.  The next level of the architecture is shown as column headings.  An “x” is placed in each column (architectural element) that the section or requirement that applies to that architectural element.

Then the next level of the architecture element’s requirements can have a requirement invoking the applicable allocations of the matrix for that specific architectural element.  There are various types of applicability matrices.  One type lists all the design and construction standards and regulations  that the project says is applicable to your system and allocates those standards (documents) to the subsystems.  Another type is an applicability matrix for an individual document, where specific sections or requirements within that document are allocated to the subsystems or other architectural element.

Verification of requirements that call out an applicability matrix can be very detailed, in that to verify that requirement, you must first verify all the individual requirements allocated via the applicability matrix.   When using a Requirement Management Tool (RMT), it is important that the allocation and traceability links implied by the matrix are documented.  If done correctly the RMT can generate the applicability matrices for you.

See the next post: “Guidelines for Referring to Other Documents in Your Requirements Document.”

If you have any other questions on requirements, feel free to ask your question on our “Ask the Experts” page and we will do our best to provide a timely response.

Tags: , , , , ,
Posted in Ask the Experts, Requirement Development, Requirement Management, Writing Requirements | Tagged , , , , , | 2 Comments

2 Responses to "How to Refer to Other Documents within your Requirement Document"

Leave a reply