Guidance On Requirement Development: November
Guidance On Requirement Development: November
604 2022
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
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
Contents
Contents 4
Introduction 5
3. Content types 14
3.1 Normative and informative content 14
3.2 Engineering specifications for design or equipment procurement 14
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.
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
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.
6
Guidance on requirement development
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.
7
Guidance on requirement development
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.
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.
8
Guidance on requirement development
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
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.
9
Guidance on requirement development
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.
2.4 Headings
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
Use “will”, “could” or “might” for informative text (notes). Do not use “shall” in informative text.
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.
Limit the use of “may” in specifications that will be used as part of a bid or procurement
cycle, or in design specifications.
Example:
11
Guidance on requirement development
Example:
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.10 Numbering
Headings and sub-headings should be numbered.
12
Guidance on requirement development
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.
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
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
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.
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.
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 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]