REPORT FEBRUARY

604 2021

Guidance on requirement development

Acknowledgements
This Report was developed by the IOGP Standards Committee.

Front cover photography used with permission courtesy of

© NickyLloyd/iStockphoto and © francisblack/iStockphoto

About
Projects in the oil and gas industry are large and complex, and project
execution can be negatively affected by unclear or ambiguous technical
requirements. Greater precision in the drafting of requirements for use
in the oil and gas industry will make projects easier to manage and
reduce risk. This guidance draws from good practices across the industry
and has been applied by some Member Companies and in IOGP JIPs
to improve the quality of technical writing. This guidance, supported by
training and appropriate review processes, is recommended to be applied
by standards development organisations to prepare technical content
for effective digital application.

Feedback

IOGP welcomes feedback on our reports: publications@iogp.org

Disclaimer

Whilst every effort has been made to ensure the accuracy of the information
contained in this publication, neither IOGP nor any of its Members past present or
future warrants its accuracy or will, regardless of its or their negligence, assume
liability for any foreseeable or unforeseeable use made thereof, which liability is
hereby excluded. Consequently, such use is at the recipient’s own risk on the basis
that any use by the recipient constitutes agreement to the terms of this disclaimer.
The recipient is obliged to inform any subsequent recipient of such terms.

This publication is made available for information purposes and solely for the private
use of the user. IOGP will not directly or indirectly endorse, approve or accredit the
content of any course, event or otherwise where this publication will be reproduced.

Copyright notice

The contents of these pages are © International Association of Oil & Gas Producers.
Permission is given to reproduce this report in whole or in part provided (i) that
the copyright of IOGP and (ii) the sources are acknowledged. All other rights are
reserved. Any other use requires the prior written permission of IOGP.

These Terms and Conditions shall be governed by and construed in accordance

with the laws of England and Wales. Disputes arising here from shall be exclusively
subject to the jurisdiction of the courts of England and Wales.
 REPORT FEBRUARY
604 2021

Guidance on requirement
development

Revision history

VERSION DATE AMENDMENTS

1.0 February 2021 First release

Guidance on requirement development

Contents

Introduction 5

1. Characteristics of a good requirement 6

2. Standard technical writing conventions 9

2.1 ‘Exception style’ requirements 9
2.2 Notes 9
2.3 Tables and figures 9
2.4 Headings 10
2.5 Use of shall, should, and may 10
2.5.1 Definition of ‘recommendation’ 11
2.5.2 Definition of ‘permission’ 11
2.6 Scope of document 11
2.7 Organizational references 11
2.8 Single audience 11
2.9 Use case 11
2.10 Numbering hierarchy 12
2.11 Reference to datasheets 12
2.12 Discretionary statements 12
2.13 Rationale 12

3. Requirement types 13
3.1 Technical 13
3.2 Contractual 13
3.3 Information 13
3.4 Calculation basis 14
3.5 Operational 14

4. Examples of good and bad requirements 15

4
Guidance on requirement development

Introduction

This guidance was originally developed for JIP33 equipment specifications. However, its use will
extend to design and activity specifications for JIP33 as well as other IOGP specification style
documents. In addition, IOGP Members may use this guidance for company specifications.

The objective of this guidance is to deliver requirements that are consistent across JIP33 and other
IOGP specifications, promote standardisation, and are ready to be digitised.

This guidance aligns with the following material on technical writing:

• INCOSE, Guide for Writing Requirements, INCOSE-TP-2010-006-02, Rev. 2
• ISO/IEC Directives, Part 2: Principles and rules for the structure and drafting of ISO and IEC
documents

Oil and gas projects are large, complex, and involve many participants. Project execution is impacted
by the clear definition of technical requirements and the smooth transfer of information through the
supply chain.

Technical standards and specifications have tended to be a mixture of narrative, guidance, and
prescriptive content. The ambiguity arising from this mixture increases uncertainty and risk and can
be difficult to manage. One improvement that the oil and gas industry can make now is to be more
precise in defining requirements.

Moreover, an examination of the digital management of requirements has highlighted that

improvements are needed in non-digital aspects. Digital systems can help with the organization,
processing, and communication of content, while better requirement writing practices will facilitate
digitalisation and better decision making.

This guidance draws from good practices across industry and has been applied by some member
companies and in IOGP JIPs to improve the quality of technical writing. This guidance, supported by
training and appropriate review processes, is recommended to be applied by standards development
organizations to prepare the technical content for effective digital application.

5
Guidance on requirement development
1. Characteristics of a good requirement
The table below lists the criteria for ‘good’ requirements, along with a definition of that criterion
in a requirements writing context, and finally considerations for those writing requirements.
The considerations include rhetorical questions, examples of a ‘good’ requirement, and advice
on sentence construction.
Table 1: Criteria, definitions, and considerations for writing good requirements
Criteria Definition
Necessary Adds specific value to
business delivery. If not
included, a deficiency
in capability will exist
which cannot be fulfilled
by implementing other
requirements.
Feasible Can be achieved within known
constraints (e.g., regulatory,
technical, legal, cost, schedule)
Avoid aspirational requirements.
Verifiable Structured and worded
such that its realisation can
be proven (verified) to the
customer’s satisfaction.
Unique Requirements cannot
contradict or repeat other
requirements in your
requirements architecture.
Considerations, examples, and rationales
• Does this prevent a major accident or reduce major accident risk?
• Does this prevent a fatality?
• Does this prevent a safety incident?
• What would happen if this was removed from our practice, i.e.,
what would be the impact on safety, reliability, operational
performance, lifecycle cost?
• Does this make us competitive?
• Is it personal preference? Reference to an internal organization
or role may indicate this.
• Can this requirement be implemented within known constraints?
• Each requirement can be verified precisely.
• Avoid non-measurable quantifiers, e.g., “readily”, “clearly”,
“proven”, “early life”, “efficiently”, “enough”, or “medium-sized”.
• Avoid non-specific temporal terms, e.g., “eventually”, “later”,
or “brief”. If a term is not defined precisely, risk and cost may
increase, particularly if the requirement is used in a contract.
• Is the requirement repeated elsewhere?
• In terms of the specification, is the requirement global, or specific,
e.g., to an item of equipment, environment, or asset? If global,
it only needs to be mentioned once, in a general section, rather
than in specific subsections
Global requirement example: HP/LP interfaces shall be protected
from all credible causes of overpressure
• Is there another document type or discipline area that is more
appropriate for this requirement?
6
Guidance on requirement development
Criteria Definition
Subject The single thing to which the
requirement refers. This can
include the function, person,
system, or subsystem.
Singular State a single capability,
characteristic, constraint,
or quality factor. A good
requirement has a single
requirement. Avoid use
of “and”.
Considerations, examples, and rationales
A single requirement reduces ambiguity and conflict. It is also
essential for digitalisation where verification, information, and
attributes are linked to requirements.
• Each requirement usually has one shall statement. There may
be two “shalls” if they relate to one requirement, but this would
be exceptional.
• Each requirement has a unique ID.
• Maximum of one requirement per sentence.
• Lists:
- Lists of multiple independent shall requirements should be
avoided. For example, the statement “the system shall contain
the following“, followed by a list of 10 different independent shall
requirements, contains multiple independent requirements and
is not advisable.
- Lists are acceptable in other circumstances, e.g., listing options.
For example, the statement “the system shall meet one of the
following”, followed by a list of possible qualifying conditions,
is acceptable.
7
Guidance on requirement development
Criteria Definition
Clear and Stated in such a way that it
Concise can be interpreted in only
one way. Avoid placing
rationale statements in
requirement statements.
Considerations, examples, and rationales
Avoid complex sentences (those with a dependent clause) and
other sources of ambiguity. Complex sentences are prone to
misinterpretation at point of use.
• Use short active forms with clarity on subject and
outcome. Minimise use of passive forms. Rule of thumb for
number of words per sentence is 25. More than this is acceptable,
but clarity should be checked.    
• A rule of thumb is that if a user needs to read a sentence twice
to understand it, the sentence needs to be rewritten.
• Conditional constructs (if, for, etc.) should be avoided if possible.
If a conditional construct is used, the condition should be at the
beginning of the sentence. If a conditional construct is necessary,
use “if” rather than “when” or “where”. “When” shall be used
only to specify time dependent requirements. “Where” shall
be used only to specify location dependent requirements.
• Avoid ambiguity, e.g., multiple conjunctions:
Example before:
The flange shall be fastened either by gluing and clamping or riveting.
Example after:
The flange shall be fastened by one of the following:
1. Gluing and clamping
2. Riveting
• Limit use of unnecessary words and universal qualifiers such as
“a”, “all”, “any”, each”, “every”, “the”, often. If appropriate, replace
with specific values.
Example before:
Every high-voltage switching device shall have sets of volt free
auxiliary contacts.
Example after:
High-voltage switching devices shall have sets of volt free auxiliary
contacts.
Example before:
Any main circuit hardware or equipment that is withdrawable shall be
fitted with a panel number locator label.
Example after:
Main circuit hardware or equipment that is withdrawable shall be
fitted with a panel number locator label.
• Avoid use of ‘etc.’ because it is inherently ambiguous.
• Minimise use of cross-referencing pronouns, e.g., “it”, “this”, “that”,
“he”, to avoid ambiguity on subject or object. Instead, repeat nouns
in full to refer to nouns in other requirements.
8
Guidance on requirement development

2. Standard technical writing conventions

This section provides guidance and examples on how to apply common industry standard technical
writing practice.

2.1 ‘Exception style’ requirements

Specifications are written as exceptions to industry standards. Requirements in
specifications occur for one of three reasons.
• Add to, modify, delete, or replace a clause in the industry standard. When modifying
a clause in the base industry standard use add, replace, delete the industry standard
clauses and reference the minimum original text and ensure amended text is clearly
identified. To avoid ambiguity, it may be necessary to be more specific. For example,
“Replace second sentence beginning ‘The purchaser shall ,,,’ with: ‘…..’ “.
• Selection of optionality in industry standards, such as:
– While the standard provides options A, B or C, the operator wants to specify
one option only
– A standard calls for a requirement subject to owner’s discretion, and the
operator does not want the requirement
• Not covered by industry standard

2.2 Notes
Use notes for information and context where necessary to enable accurate interpretation of
the requirement. Do not include requirements or recommendations in notes. Keep notes to
a minimum.

2.3 Tables and figures

Do not include requirements in the notes for tables and figures.

Number and label all tables and figures and reference them by number (instead of ‘below’).
Follow the numbering style of the source standard while making sure there is no conflict,
such as two figures with the same number.

9
Guidance on requirement development

2.4 Headings
Do not put requirements under a heading that is followed by a subheading.
The example below shows correct placement of shall statements. ‘a’ and ‘b’
are regarded as subheadings.

Example:

4.4. Pressure vessel components

In certain countries, pressure containing parts, such as shell, bonnet, channel, headers,
and tubes, are considered pressure vessels and are subject to statutory control and survey
by external inspection authorities, especially in steam duty.

a. P
 rinciples of pressure vessel inspection described in API 510 shall be applied to
these components.

b. S
 ome designs of exchanger, such as fixed tubesheets, cannot be dismantled, and
internal access is limited via nozzles. In these cases, inspection procedures shall
specify other means to facilitate thorough examination of shell, usually involving
remote visual and NDE.

2.5 Use of shall, should, and may

General principles regarding the use of ‘shall’, ‘should’, and ‘may’ in written requirements:
• Only use ‘shall’ for instructions, ‘should’ for recommendations, and ‘may’ for permissions.
• Avoid implied requirements. Don’t use “will”, “needs to”, “must”, ‘is to be’, etc.,
to imply requirements.
• Use “will”, “could” or “might” for informative text (notes). Do not use “shall” in
narrative text.
• A ‘should’ in a lower level requirement may depend on a ‘shall’ in a higher level
requirement but never the other way around. The example below shows correct
placement of should and shall statements.

Cleaning of utility systems shall be performed using dry air.

Pressurised air blowing should be used for cleaning utility systems

• Do not use “should” in specifications that will be used as part of a bid or

procurement cycle.
• Limit the use of “should” in design specifications.
• Limit the use of “may” in specifications that will be used as part of a bid or
procurement cycle, or in design specifications.
• Use of ‘may’ in a specification is likely to be linked to excess definition of solutions
and should be tracked (By saying you may do “a” or “b”, we are limiting to only “a”
or “b”, so it is then “you shall do “a” or “b”).
• Do not use “shall” or “should” in notes, tables, or introductions.

10
Guidance on requirement development

2.5.1 Definition of ‘recommendation’

Per ISO/IEC Directives Part 2: “[Recommendation] conveys a suggested possible course
or course of action deemed suitable without necessarily mentioning or excluding others.”
Recommendation is expressed by the use of “should”.

2.5.2 Definition of ‘permission’

Per ISO/IEC Directives Part 2: “[Permission] conveys consent or liberty (or opportunity)
to do something. Permission is expressed by the use of “may”. “May” is not used as the
normal linguistic way in English (might or could).”

2.6 Scope of document

Per ISO/IEC Directives Part 2, a scope is a mandatory and normative element of a
document. A document’s scope shall not contain requirements, recommendations,
or permissions.

2.7 Organizational references

Avoid organizational references, especially those that may be company specific,
e.g., “Approval shall be obtained by XYZ Quality department.”

2.8 Single audience

Avoid assigning responsibility to a supplier or manufacture on a requirement by
requirement basis. Use of the term “manufacturer” is acceptable if used as an adjective.

Example:

“Preparation for shipment shall be in accordance with Manufacturer’s standards….”

does not assign responsibility to the manufacturer.

Example:

“For busbar earthing via withdrawable truck mounted earthing switch, the Manufacturer
shall provide one earthing truck for each HV switchboard assembly,” does assign
responsibility to the manufacturer. This could be rewritten as: “For busbar earthing via
withdrawable truck mounted earthing switch, one earthing truck shall be provided for
each HV switchboard assembly.”

2.9 Use case

The use case for JIP33 specifications should be defined in the Introduction or other
supporting document so that it is applied correctly.

11
Guidance on requirement development

2.10 Numbering hierarchy

As a document, the hierarchy of numbering and subnumbering should only be used
to identify where a requirement applies in the context of the higher-level requirement,
or to list conditions that apply for a singular requirement.

2.11 Reference to datasheets

Based on a typical bid-review-purchase cycle, the procurement package will use this
specification plus an over-riding data sheet and configuration sheet to define the purchased
equipment. Defining this hierarchy and flow means that the ‘Unless otherwise specified
in the datasheet” type of comments come out.

2.12 Discretionary statements

Avoid using statements that depend on choices to negate the requirement in the
specification. This is to avoid ambiguity and inherent conflict. It is expected that a
specification will have defined the applicable requirements for the removal of discretionary
or contradictory content before issuing to recipient. Common examples of statements
to avoid include:
• “unless otherwise specified” or “unless otherwise specified by the purchaser”
• “unless otherwise agreed or “as “otherwise agreed with the purchaser”
• “requirements subject to owners’ discretion”
• “requirements subject to purchaser approval”

If such requirements are defined in the parent standard and are material to the clarity
of the requirement, consider the following options:
• If an option or input value needs to be defined by the purchaser, it needs to be
managed as a datasheet attribute and the clause amended to read “as specified
in the datasheet”
• Delete “unless otherwise specified” so the specifier or supplier makes a conscious
decision to deviate from the requirement and manages the change via tender
clarification, technical query or contract amendment.

2.13 Rationale
It is good practice to define a rationale or justification statement to briefly define why the
requirement is necessary. The representation of this statement in a written output of the
requirement can be optional, but it is valuable to require a rationale per requirement in
the digital database.

The rationale confirms the validity of the requirement as being necessary, typically clarifies
the intent of the requirement to aid with interpretation, and captures the knowledge of why
the requirement was added.

12
Guidance on requirement development

3. Requirement types

3.1 Technical
A technical requirement defines a characteristic that can be demonstrated in the final
product. A process that needs to be carried out to demonstrate a characteristic can
be included in a technical requirement so long as there is a characteristic that can be
demonstrated in the final product. In a requirements management database, specified
processes should have rationales.

A technical review process that results in a deliverable such as classification, criticality

rating, etc., is also considered a technical requirement. Examples include functional
safety assessment or HAZOP.

Requirements that define a management system are not technical requirements.

3.2 Contractual
Contractual requirements are typically not part of engineering practice and should be
avoided. However, there might be justification for inclusion to define a condition of a
technical requirement or order of precedence. Contractual clauses that overlap with
elements of a standard contract, e.g., warranties or quality management approaches,
should be avoided.

In some cases, contractual requirements may be included in technical specifications

because it cannot be confirmed that they will be included in a contractual document.
Inclusion of these contractual requirements should be considered as a transitional step.
In such cases, the contractual requirement should be indicated as being a contractual
requirement within the database. In future, once all documents have been digitised,
including contractual documents, there will be no need to maintain contractual
requirements within technical specifications.

3.3 Information
Information requirements include information, deliverables or data to be produced.
Typically, these are linked to a technical requirement or for handover to operations.

The specification should identify information needs. These information needs are then
documented in the Information Requirements Specification (IRS). The IRS should not
be creating an information need that is not in the specification.

Example:

If two check valves as described in clause 7.020 are used, their use shall be documented
in the relief and overpressure protection dossier.

13
Guidance on requirement development

3.4 Calculation basis

These requirements include assumptions to be applied when carrying out calculations.
They are typically used when industry standards are silent on a topic.

Example:

When sizing a pressure relief device, discharge coefficient, backpressure correction factor,
viscosity correction factor, and orifice area shall be from manufacturer data.

3.5 Operational
Requirements to be carried out when equipment is in service and not related to design
or handover are typically not part of engineering specifications for design or equipment
procurement.

Example:

Check valves credited for relief rate flow reduction shall be maintained and inspected to
ensure that they meet any safety critical reliability requirements.

14
Guidance on requirement development

4. Examples of good
and bad requirements
Table 2: Examples of good and bad requirements

Topic Poor example Good example Comment

Duplication The MOC process shall If the application of
be followed to assess Management of Change
changes affecting the (MOC) is contained in a
relief system design. mandated document it
should not be necessary to
repeat it in other standards.

In addition, the application

of MOC is not a technical
requirement.

Duplication Causes of overpressure to be This is duplicated with

evaluated shall include those industry standard.
listed in API Std 521
Also, the reference is
general – the standard has
260 pages; the causes of
overpressure section is
over 60 pages. Where is the
requirement pointing?

Duplication A HAZOP shall be performed If the application of HAZOP

in accordance with GP 4802 is defined in a mandated
for the entire package. document it should not be
necessary to repeat it in
other standards.

Technical Evaluations of indications These are acceptable only

requirement shall be performed by Level if they do not duplicate a
II or III personnel only. referenced industry standard.

Personnel performing NDT

shall be approved to ASME
Level 2.

Skirt attachment welds of

ferritic materials shall be
examined by MT.

Technical Rupture disks shall be

requirement nonfragmenting.

Not verifiable Methods of calculation shall “Early stage” is not defined.

be defined at an early stage Also, this requirement does
of the design. not relate to a characteristic
that can be demonstrated in
the final product.

15
Guidance on requirement development

Topic Poor example Good example Comment

Technical For letdown stations The purpose of the analysis,

requirement incorporating power in terms of a characteristic
recovery turbines, a detailed of the final product, is not
engineering analysis shall defined. It may be better
be completed. to state: “Letdown stations
incorporating power recovery
turbines shall be protected
from overpressure.”

Contractual Company and the Company This requirement should be

appointed representative in a contractual document
shall at all times have rather than a technical
access to the workshops and specification.
testing facilities, including
workshops of subsuppliers
engaged in supplying
material or in fabricating
the equipment for the
purpose of inspecting the
purchased equipment.

16
Guidance on requirement development

This page is intentionally blank

17
 www.iogp.org
Registered Office Brussels Office Houston Office
City Tower Avenue de Tervuren 188A 15377 Memorial Drive
Level 14 B-1150 Brussels Suite 250
40 Basinghall Street Belgium Houston, TX 77079
London EC2V 5DE USA
T +32 (0)2 790 7762
United Kingdom
reception-europe@iogp.org T +1 (713) 261 0411
T +44 (0)20 3763 9700 reception-americas@iogp.org
reception@iogp.org

Projects in the oil and gas industry

are large and complex, and project
execution can be negatively affected
by unclear or ambiguous technical
requirements. Greater precision in
the drafting of requirements for use
in the oil and gas industry will make
projects easier to manage and reduce
risk. This guidance draws from good
practices across the industry and
has been applied by some Member
Companies and in IOGP JIPs to
improve the quality of technical
writing. This guidance, supported
by training and appropriate review
processes, is recommended to be
applied by standards development
organisations to prepare
technical content for effective
digital application.