REPORT NOVEMBER

604 2022

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 energy 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 energy 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
developing organizations to prepare technical content for effective digital
application.

Feedback

IOGP welcomes feedback on our reports: [email protected]

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.

Please note that this publication is provided for informational purposes and adoption of any of its recommendations is at the discretion of the user. Except
as explicitly stated otherwise, this publication must not be considered as a substitute for government policies or decisions or reference to the relevant
legislation relating to information contained in it.

Where the publication contains a statement that it is to be used as an industry standard, IOGP and its Members past, present, and future expressly disclaim all
liability in respect of all claims, losses or damages arising from the use or application of the information contained in this publication in any industrial application.

Any reference to third party names is for appropriate acknowledgement of their ownership and does not constitute a sponsorship or endorsement.

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 NOVEMBER
604 2022

Guidance on requirement
development

Revision history

VERSION DATE AMENDMENTS

Updated definitions for characteristics of a good requirement (Section 1).

2.0 November 2022 Updated standard technical writing conventions and content types (Sections 2
and 3). Replaced examples of well and poorly written requirements (Section 4).

1.0 February 2021 First release

Guidance on requirement development

Contents

Contents 4

Introduction 5

1. Characteristics of a well written requirement 6

2. Standard technical writing conventions 9

2.1 Overlay and narrative styles 9
2.2 Notes 9
2.3 Tables, figures and equations 10
2.4 Headings 10
2.4.1 Heading structure 10
2.4.2 Subheadings 10
2.5 Use of shall, should, and may 11
2.5.1 Requirement clauses 11
2.5.2 Recommendation clauses 11
2.5.3 Permission clauses 11
2.5.4 Definition of ‘requirement’ 11
2.5.5 Definition of ‘recommendation’ 11
2.5.6 Definition of ‘permission’ 12
2.6 Scope of document 12
2.7 Organizational references 12
2.8 Single audience 12
2.9 Use case 12
2.10 Numbering 12
2.11 Use of datasheets 13
2.12 Discretionary statements 13
2.13 Rationale 13
2.14 References 13

3. Content types 14
3.1 Normative and informative content 14
3.2 Engineering specifications for design or equipment procurement 14

4. Examples of well written and poorly written requirements 15

4
Guidance on requirement development

Introduction

The objective of this guidance is to deliver requirements in IOGP JIP33 and other IOGP specifications
that are consistent, promote standardization, and are ready to be digitized.

This guidance draws from good practices across industry and is closely aligned with the following
documents on technical writing:
• INCOSE, Guide for Writing Requirements, INCOSE-TP-2010-006-02, Rev. 2
• I SO/IEC Directives, Part 2: Principles and rules for the structure and drafting of ISO and IEC
documents

Energy 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 energy 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
digitalization and better decision making.

This guidance has been applied by some IOGP Member Companies to improve the quality of
technical writing. This guidance, supported by training and appropriate review processes, is
recommended to be applied by standards developing organizations to prepare technical content for
digital application.

5
Guidance on requirement development

1. Characteristics of a well written

requirement
The table below lists criteria for well written requirements. A definition of each criterion in a
requirements writing context is provided, along with considerations for those writing requirements.
The considerations include rhetorical questions, examples of a well written requirement, and advice
on sentence construction.

Table 1: Criteria, definitions, and considerations for writing good requirements

Criteria Definition Considerations, examples, and rationales

Necessary Adds specific value to • Does this requirement manage process safety risk, or personal
business delivery. If not safety risk?
included, a deficiency • Does this requirement manage the risk of an environmental
in capability will exist incident?
which cannot be fulfilled
• Does this requirement deliver target integrity, reliability, and
by implementing other
operability?
requirements.
• Does this requirement deliver the target lifecycle cost?
• Does this requirement decompose the functionality of a higher
level requirement, or summarize functions from lower level
requirements?
• What would happen if the requirement was removed? What would
be the impact on safety, reliability, operational performance,
lifecycle cost?
• Is the requirement a preference rather than a necessity?
Reference to a non-industry internal organization or role may
indicate that the requirement is a preference.

Feasible Can be achieved within known • Can the requirement be implemented within known constraints?
constraints (e.g., technical, • If absolutes are included, test that the absolutes are feasible and
legal, cost, schedule) verifiable, e.g., 6 years between overhauls. Ensure feasibility is
aligned with industry capability.
• Avoid aspirational requirements.

Verifiable Structured and worded • Each requirement is verifiable

such that its realization can • Terms can be defined. Vague terms may result in risk and cost that
be proven (verified) to the were not what were intended.
customer’s satisfaction.
• 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”.

6
Guidance on requirement development

Criteria Definition Considerations, examples, and rationales

Unique Requirements are unique. • Each requirement has an ID so that the requirement can be
uniquely identified.
• In a digital environment, requirements can be stored once and
reused rather than referenced.
• Requirements cannot contradict each other.

Subject The single thing to which the • The subject could be the function, person, system, or subsystem.
requirement refers.

Singular State a single capability, • A single requirement reduces ambiguity and conflict. This
characteristic, constraint, or criterion is essential for digitalization where verification,
quality factor. Avoid use of information, and attributes are linked to requirements.
“and”. • Each requirement usually has only one shall statement.
• Lists:
- Avoid lists of independent requirements, e.g., a lead in statement
“the system shall contain the following“, followed by a list of 10
different and independent requirements.
- Circumstances when lists are acceptable include listing options.
For example, the statement “the system shall meet one of the
following”, followed by a list of possible qualifying conditions, is
acceptable.

Example of an acceptable list:

Cable trays, channel and ladder trays shall be one of the following:
• Copper free aluminium
• Fibreglass

7
Guidance on requirement development

Criteria Definition Considerations, examples, and rationales

Clear and Stated in such a way that it • Avoid complex sentences (those with a dependent clause) and
Concise can be interpreted in only one other sources of ambiguity. Complex sentences are prone to
way. Avoid placing rationale misinterpretation at point of use.
statements in requirement • Use active form to create shorter sentences with clarity on subject
statements. and outcome. Minimize use of passive form.
• A guide for the number of words per sentence is 25. More than 25 is
acceptable but clarity of requirement should be checked.
• Conditional constructs (if, unless, etc.) should be avoided. Where
a conditional construct is used, the condition should be at the
beginning of the sentence.
• Avoid multiple conjunctions.

Example before:
During impending adverse weather conditions, ongoing surface
preparation shall be suspended if painting cannot be completed in one
go and paint cannot dry as required to withstand weather damage.

Example after:
If impending weather conditions could interrupt paint application and
drying, surface preparation shall be suspended.

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

• Avoid use of ‘etc.’ because it is inherently ambiguous.

• Minimize use of cross-referencing pronouns, e.g., “it”, “this”, “that”,
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

2.1 Overlay and narrative styles

Specifications can be overlay or narrative style.

Overlay style specifications are aligned with and make exceptions to industry standards.
Clause numbering mirrors the industry standard. Requirements in overlay style
specifications occur for one of four reasons.
• Amending a clause in the industry standard. Amendments include:
– ­ Add to existing text
– ­ Replace content in a clause
– ­ Add new content
– ­ Delete existing text

To avoid ambiguity, it may be necessary to be specific about which text is being

amended, e.g., “Replace second sentence beginning ‘The purchaser shall ‘…’ with: ‘…..’ “.
• Selection of optionality in industry standards, e.g.:
– While
­ the standard provides options A, B or C, the operator wants to specify one
option only
– A
­ standard includes a requirement subject to purchaser’s discretion, and the
purchaser does not want the requirement
• Responses to “Purchaser to specify” type statements in the industry standard
• Not covered by the industry standard

Narrative style specifications are standalone and have sequential clause numbering.
Narrative style specifications do not mirror industry standards, but industry standards can
be referenced.

2.2 Notes
Use notes for information and context related to the requirement.

Do not include requirements or recommendations in notes.

Keep notes to a minimum.

Requirements and recommendations should be useable without notes.

9
Guidance on requirement development

2.3 Tables, figures and equations

Do not include requirements or recommendations in tables, figures, and equations.

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

For narrative style documents, number tables in the order they appear.

Do not put tables inside tables.

2.4 Headings

2.4.1 Heading structure

Hierarchy of headings should only be used to identify where a requirement applies in the
context of the higher-level system.

Example:

2 Corrosion controls
2.1 Onshore arid
2.2 Onshore marine
2.3 Offshore

2.4.2 Subheadings
Do not put requirements under a heading that is followed by a subheading. The example
below shows correct placement of shall statements.

Example:

4 Speed governing
4.1 Governor
a. Engine governor shall be mechanical.
b. Set points shall be manually adjustable.
4.2 Speed indication
a. Independent method of detecting overspeed shall be provided.
b. Control range signal characteristics shall be specified.

10
Guidance on requirement development

2.5 Use of shall, should, and may

2.5.1 Requirement clauses

Use ‘shall’ in requirement clauses. Avoid implied requirements, e.g., do not use ‘will’,
‘needs to’, ‘must’ or ‘is to be’, to imply requirements.

Use “will”, “could” or “might” for informative text (notes). Do not use “shall” in informative text.

2.5.2 Recommendation clauses

Use ‘should’ in recommendation clauses.

Do not use “should” in specifications that will be used as part of a bid or procurement
cycle. Recommendation clauses increase uncertainty in outcomes because there is no
contractual obligation for a should.

Design specifications can include ‘should’ statements if they enable optimal solutions that
balance conflicting drivers.

2.5.3 Permission clauses

Use ‘may’ in permission clauses.

Limit the use of “may” in specifications that will be used as part of a bid or procurement
cycle, or in design specifications.

Example:

Painting may be done at a sub-supplier.

2.5.4 Definition of ‘requirement’

Per ISO/IEC Directives Part 2: “[Requirement] conveys objectively verifiable criteria to be
fulfilled and from which no deviation is permitted if conformance with the document is to be
claimed.”

Some companies have processes to manage deviations. In addition, overlay style

specifications are used by some companies to manage changes to industry standards.

2.5.5 Definition of ‘recommendation’

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

11
Guidance on requirement development

2.5.6 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. To avoid assigning responsibility, the requirement 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 specifications should be defined in a scope or similar section so that the
specification is applied correctly.

2.10 Numbering
Headings and sub-headings should be numbered.

Requirements, recommendations, and permissions should have individual numbers or

identifications.

List of conditions that apply to a single requirement may be numbered.

12
Guidance on requirement development

2.11 Use of datasheets

Datasheets define individual design cases. Equipment and services are designed,
purchased or built to the parameters in the datasheets.

Decision points in a standard can be resolved in the datasheet.

2.12 Discretionary statements

For equipment specifications, avoid using statements that depend on choices. 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 include a rationale to briefly define why the requirement is necessary.

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.

In a digital environment, a rationale can be included as an attribute to a requirement. For

specifications that are not managed in a digital tool, a rationale can be included as an
informative annex.

2.14 References
If a requirement is expressed by referring to an industry standard or other document, list
the reference in a reference clause.

13
Guidance on requirement development

3. Content types

3.1 Normative and informative content

Content can be normative or informative.

Normative clauses contain shall, should, or may statements. In addition, a scope is

considered a normative element.

Informative clauses help the understanding or application of content. Informative clauses

do not contain requirements, recommendations, or permissions. Examples of informative
content are notes, rationale, guidance, and informative appendices.

3.2 Engineering specifications for design or equipment

procurement
Normative clauses in engineering specifications for design or equipment procurement
define characteristics that can be demonstrated in the final product. A technical review
process that results in a deliverable such as classification, criticality rating, etc., is also
considered a technical normative clause. Examples include functional safety assessment
and HAZOP.

Commercial and contractual normative clauses are typically not included in engineering
specifications for design or equipment procurement. However, there might be justification
for inclusion to define a condition of a technical clause or order of precedence. Commercial
and contractual clauses that overlap with elements of a standard contract, e.g., warranties
or quality management approaches, should be avoided. Commercial and contractual terms
are not included in industry standards.

Normative clauses to be carried out when equipment is in service and not related to design
or handover are typically not included in engineering specifications for design or equipment
procurement.

14
Guidance on requirement development

4. Examples of well written and poorly

written requirements
Table 2: Examples of well written and poorly written requirements

Characteristic Poorly written example Well written example Comment

Content type Permanently affixed pointer This is an example of a
shall identify which piece of technical requirement.
equipment is in service.

Content type Shutdown loads shall include This is an example of a

weight of equipment. technical requirement.

Singular Vent shall have a filter Vent shall have a filter There are two requirements
against airborne foreign against airborne foreign in the poorly written
matter and terminate in matter. example.
downward facing opening.
Vent shall terminate in
downward facing opening.

Verifiable Methods of calculation shall Ability for compressor to be In the poorly written
be defined at an early stage removed shall be confirmed example, “early stage” is
of the design. by calculation. not defined and “methods of
calculation” is not a technical
characteristic.

Verifiable Use of guard elements to “Shall be considered” is not

capture debris shall be verifiable.
considered.

Content type For letdown stations Letdown stations In the poorly written
incorporating power incorporating power recovery example, the purpose of
recovery turbines, a detailed turbines shall be protected the analysis, in terms of a
engineering analysis shall be from overpressure. characteristic of the final
completed. product, is not defined.

Content type Company and Company Requirement should be in

appointed representative a contractual document
shall have access to rather than a technical
workshops and testing specification.
facilities.

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

IOGP Headquarters www.iogp.org

City Tower, 40 Basinghall St, London EC2V 5DE, United Kingdom
T: +44 (0)20 3763 9700
E: [email protected]

IOGP Americas IOGP Asia Pacific IOGP Europe IOGP Middle East & Africa
T: +1 713 261 0411 T: +61 4 0910 7921 T: +32 (0)2 790 7762 T: +20 120 882 7784
E: [email protected] E: [email protected] E. [email protected] E: [email protected]