How to Refer to Guidance Documents in Your Requirements

Posted on: October 15th, 2012 by Lou Wheatcraft 1 Comment

We received the following question via our “Ask the Experts”  page:

Can you say ‘shall be guided by’ when referring to a large section in a document that specifies in great detail functionality (ies) that you need to design into your product? To do everything would be prohibitively expensive.”

The short answer is – no you shouldn’t have a requirement that says “shall be guided by” because it is ambiguous and not verifiable.

However, looking beyond the short answer, the issue is more complicated.

Guidance Documents

It is common practice for organizations to document years of experience-based lessons learned into guidance documents for their organization and product line.  These documents are commonly referred to as: “Business Rules”, “Golden Rules for Design”, “Design Guidelines”, “Principles of Design”, etc.  Some of the best practices apply to the people designing a product (processes to follow), to the product itself (functionality, performance, and quality requirements), and to how to test the product (guidance for verification and validation).  Some of these are written as requirements (“shall” statements) and some are written as suggestions and guidance (“should” statements), also referred to as goals.

When referring to these documents, it is important to not mix the different types of statements.  If it involves process guidelines, then the applicable statements would go in a project plan or Statement of Work.  If the guidelines apply directly to your product, then include the applicable statements in your product specification.  If it applies to how to do tests, verification, and validation, then include the statements in your Master Test, Verification, and Validation Plan.

Shall vs Should

Part of the question stated “functionality (ies) that you need to design into your product”.  This implies requirements.  If requirements then they are not suggestions, but are binding, and will need to be verified.   The trick is to review the guidance document and only refer to those requirements that apply to your product and that you will need to show compliance that you have met those requirements.

If the guidance documents are really industry standards or regulations that you have to meet, then you need to call these out directly as requirements.   A detailed discussion on referring to other documents can be found in an earlier post: How to Refer to Other Documents in your Requirement Document

The basic rationale that was given for stating “shall be guided by” – to do everything would be prohibitively expensive – implies you have a choice and that not all the product requirements in the guidance are required.  If this is the case, you need to clearly determine what guidance requirements apply to your specific product, are expected, are binding, and will be verified – invoke these as requirements.  For those that you do have a choice but are not mandatory, call them out as goals “should” statements.   A detailed discussion on the use of shall, should, and will can be found in an earlier blog post: Using the Correct Terms: Shall, Will, Should

Priorities and Risk

Which guidance statements you call out as requirements or goals largely is a question of priorities and risk mitigation.  If you are lucky enough to have the guidance document prioritize the importance of the requirements, then you probably would not want to compromise on the high priority guidance requirements, but due to cost or schedule considerations, may be able to compromise on the lower priority requirements.   Risk would be a major consideration in making this determination.  If by not implementing a high priority guidance requirement could result in something bad happening, increase the chances of something bad happening, or increase the impact of a bad thing happening, then the requirement is high risk and you should not compromise on its implementation.   Otherwise, you have to weigh the risk vs cost and schedule and maybe could make a case for not implementing that requirement.  In this case either don’t call it out at all or make it a goal.  A detailed discussion on priorities can be found in a previous post: How to Prioritize Requirements

Verification and Validation

In the end, what you call out and implement comes down to what the customer expectations are and which of the guidance statements are binding.  Those that are binding are subject to system verification showing that the designed and built product meets those requirements.   System validation will show that the product meets customer expectations, accomplishes its intended purpose in its operational environment.

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, RE News, Requirement Development, Requirement Management | Tagged , , , , , | 1 Comment

One Response to "How to Refer to Guidance Documents in Your Requirements"

Leave a reply