|
|
API Document Format
and Style Manual
REVISION DATE: OCTOBER 2020
All rights reserved. No part of this work may be reproduced, translated, stored in a retrieval system, or transmitted by any means,
electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from the publisher. Contact the
Publisher, API Publishing Services, 200 Massachusetts Avenue, NW, Suite 1100, Washington, DC 20001.
Contents
Page
1
Scope
1
2
Normative References
1
3
Terms and Definitions
1
4
General Principles
2
4.1
Document Types
2
4.2
Expression of Provisions
3
4.3
Homogeneity
5
4.4
Units and Quantities
6
4.5
Digitization
6
4.6
Page Proof Review Guidelines
8
5
Document Structure
9
5.1
General
9
5.2
Normative and Informative Text
9
5.3
Subdivision of Subject Matter
9
6
Document Elements
12
6.1
Lists
12
6.2
Tables
12
6.3
Figures
13
6.4
Equations
13
6.5
References
14
6.6
Order of Sections within a Document
16
6.7
Other Informative Elements
20
6.8
Use of Trade Names
21
Annex A (informative) Writing Tips
22
Annex B (normative) Tables
25
Annex C (normative) Lists
27
Annex D (normative) Figures
28
Annex E (normative) Drafting Terms and Definitions
30
Annex F (normative) Use of Bullets to Indicate Purchaser Decision
33
Bibliography
34
Tables
1
Verbal Forms to Express Mandatory Provisions (Requirements)
4
2
Verbal Forms to Express Recommendations
4
3
Verbal Forms to Express Permission
5
4
Verbal Forms to Express Possibility and Capability
5
5
Guidance for Writing Requirements
7
6
Names of Divisions and Subdivisions
9
7
Examples of Hanging Paragraphs
11
v
Introduction
This manual establishes the preferred API style for the preparation of new and revised standards. This manual is
not intended to be a guide to the procedural development of standards. This information can be found in the
Procedures for Standards Development issued by the API Standards Department.
For this document only, a box is placed around examples in order to distinguish them from the rest of the text (see
6.7.3 for information on how to format examples in new and revised standards).
API Document Format and Style Manual
1 Scope
This document covers only the most basic information about the API format as it has been adapted to
API layout and U.S. conventions, and should be used as a guide by API standards development
committees. These guidelines are intended to ensure that API standards are presented as uniform as
practicable, irrespective of the technical content.
2 Normative References
The following documents are referred to in the text in such a way that some or all of their content
constitutes requirements of this document. For dated references, only the edition cited applies. For
undated references, the latest edition of the referenced document (including any addenda) applies.
API Procedures for Standards Development
3 Terms and Definitions
For the purposes of this document, the following definitions apply.
3.1
consensus
Substantial agreement has been reached by directly and materially affected interests, which signifies the
concurrence of more than a simple majority, but not necessarily unanimity.
NOTE Consensus requires that all views and objections be considered, and that an effort be made toward their
resolution. [ANSI Essential Requirements, Annex A]
[SOURCE: ANSI Essential Requirements, Annex A]
3.2
informative
Elements or provisions intended to assist in the understanding or use of the document or provide
contextual information about its content, backg3round, or relationship with other documents.
3.3
informative elements
Elements that: a) identify the document, introduce its content, and explain its backg3round, development,
and its relationship with other documents; or b) provide additional information intended to assist the
understanding or use of the document.
3.4
normative
Elements or provisions that are mandatory to claim compliance with the standard.
3.5
normative elements
Elements that describe the scope of the document and set out provisions that are required to implement
the document.
3.6
page proof review
The process involving the critical review of edited standards by the industry subject-matter experts prior
to publication.
1
2
API DOCUMENT FORMAT AND STYLE MANUAL
3.7
provision
Expression in the content of a normative document that takes the form of a statement, an instruction, a
recommendation, or a requirement.
3.8
recommendation
Expression in the content of a document conveying a suggested possible choice or course of action
deemed to be particularly suitable, without necessarily mentioning or excluding others.
NOTE 1
Recommendations are expressed using the verbal forms specified in Table 2.
NOTE 2
In the negative form, a recommendation is the expression that a suggested possible choice or course of
action is not preferred but it is not prohibited.
[SOURCE: ISO Directives Part 2, 7th edition]
3.9
requirement
Expression in the content of a document conveying objectively verifiable criteria to be fulfilled and from
which no deviation is permitted if compliance with the document is to be claimed.
[SOURCE: ISO Directives Part 2, 7th edition]
NOTE Table 1 specifies the verbal forms for the expression of requirements.
3.10
statement
Expression in the content of a document conveying information.
NOTE Table 3 specifies the verbal forms for indicating a course of action permissible within the limits of the
document. Table 4 specifies the verbal forms to be used for statements of possibility and capability.
4 General Principles
4.1 Document Types
Bulletin
Documents that convey technical information on a specific subject or topic and are generally issued on a
one-time basis, are not standards, and are not addressed by the API Procedures for Standards
Development.
Code
A document intended for adoption by regulatory agencies or authorities having jurisdiction.
Recommended Practice
A document that communicates recognized industry practices.
Specification
Documents that are written in such a way as to facilitate communications between purchasers,
manufacturers, and/or service suppliers. Specifications may include datasheets that may be used in
industrial transactions.
API DOCUMENT FORMAT AND STYLE MANUAL
3
Standard
A document, established by consensus and approved by a recognized body, that provides, for common
and repeated use, rules, guidelines, or characteristics for activities or their results, aimed at the
achievement of the optimum degree of order in a given context. Standards typically include elements of
specifications and recommended practices.
NOTE For the purposes of this document, the term “standard” or “document” is used as a generic description for all
document types.
Technical Report
See 4.1.1.
4.2 Expression of Provisions
General
Every document contains terms that express the provisions the reader needs to demonstrate compliance
with the requirements. A document does not in itself impose any obligation upon anyone to follow it.
However, such an obligation may be imposed, for example, by legislation or by a contract. Consistent
use of the correct verbal form in every provision avoids ambiguity and simplifies the task of the user of
the document. The user will know exactly what has to be done to claim conformance with the document,
what should be done to facilitate the procedure, and what can be done if desired. The verbal forms
necessary to express these provisions are specified as being “shall” (requirement), “should”
(recommendation), “may” (permission), and “can” (possibility and capability). These terms are defined as:
a) shall-is used to indicate that a provision is mandatory;
b) should-is used to indicate that a provision is not mandatory, but recommended as good practice;
c) may-is used to indicate that a provision is optional;
d) can-is used for statements of possibility or capability.
See Annex A for additional information and examples to help in the writing of API documents.
Expressing Mandatory Provisions (Requirements)
4.2.2.1
General
A clear distinction shall be made between requirements, statements, and recommendations. Contractual
requirements (concerning claims, guarantees, covering of expenses, etc.) and legal or statutory
requirements shall not be included.
In some product standards, it may be necessary to specify that the product shall be accompanied by
warning notices or by instructions to the installer or user, and to specify their nature.
Documents listing characteristics for which suppliers are required to state values not specified by the
document itself shall specify how such values are to be measured and stated.
Table 1 summarizes the verbal forms of expression that shall be used to indicate requirements to be
followed in order to conform to the document and from which no deviation is permitted.
4
API DOCUMENT FORMAT AND STYLE MANUAL
Table 1-Verbal Forms to Express Mandatory Provisions (Requirements)
Verbal Form
Equivalent Expressions for Use in Exceptional Casesa
shall b, c
is to
is required to
it is required that
has to
only...is permitted
it is necessary
needs to
shall not
is not allowed (permitted) (acceptable) (permissible)
is required to be not
is required that...be not
is not to be
need not
do not
a The equivalent expressions given the second column shall be used only in
exceptional cases when the form given in the first column cannot be used for
linguistic reasons.
b Do not use “must” as an alternative for “shall” (this will avoid any confusion
between the requirements of a document and jurisdictional regulatory obligations).
c Do not use “may not” when “shall not” is meant, i.e. to express a prohibition.
Avoid using vague expressions that are not truly informative and may cause the reader to make an
incorrect assumption. Words like “very,” “all,” “every,” “never,” “excessive,” “slightly,” “approximately,”
“nearly,” or “significant” are not useful.
The use of bullets to indicate purchaser decisions is addressed in Annex F.
Expressing Recommendations
Table 2 summarizes the verbal forms that shall be used to indicate:
a) that, among several possibilities, one is recommended as particularly suitable, without mentioning or
excluding the others;
b) that a certain course of action is preferred, but not necessarily required; or
c) that (in the negative form) a certain possibility or course of action is discouraged but not prohibited.
Table 2-Verbal Forms to Express Recommendations
Verbal Form
Equivalent Expressions for Use in Exceptional Cases a
should
it is recommended that
ought to
should not
it is not recommended that
ought not to
a The equivalent expressions given in the second column shall be used only in exceptional cases
when the form given in the first column cannot be used for linguistic reasons.
API DOCUMENT FORMAT AND STYLE MANUAL
5
Expressing Permission
Table 3 summarizes the verbal forms that shall be used to indicate a course of action permissible within
the limits of the document.
Table 3-Verbal Forms to Express Permission
Verbal Form
Equivalent Expressions for Use in Exceptional Cases a
is permitted to
may
is allowed
is permissible
it is not required that
need not
no...is required
Do not use “possible” or “impossible” in this context.
Do not use “can” instead of “may” in this context.
Do not use “might” instead of “may” in this context.
NOTE “May” signifies permission expressed by the document, whereas “can” refers to the
ability of a user of the document or to a possibility open to him/her.
a The equivalent expressions given in the second column shall be used only in exceptional
cases when the form given in the first column cannot be used for linguistic reasons.
Expressing Statements of Possibility and Capability
Table 4 summarizes the verbal forms that shall be used for statements of possibility and capability,
whether material, physical, or causal.
Table 4-Verbal Forms to Express Possibility and Capability
Verbal Form
Equivalent Expressions for Use in Exceptional Cases a
can
be able to
there is a possibility of
it is possible to
cannot
be unable to
there is no possibility of
it is not possible to
NOTE See Note in Table 3.
a The equivalent expressions given in the second column shall be used only in
exceptional cases when the form given in the first column cannot be used for linguistic
reasons.
4.3 Homogeneity
Uniformity of structure, style, and terminology shall be maintained not only within each document, but
also within a series of associated documents. The structure of associated documents and the numbering
of their sections shall, as far as possible, be identical. Analogous wording shall be used to express
analogous provisions; identical wording shall be used to express identical provisions.
The same term shall be used throughout each document or series of associated documents to designate
a given concept. The use of an alternative term (synonym) for a concept already defined shall be
avoided. As far as possible, only one meaning shall be attributed to each term chosen.
6
API DOCUMENT FORMAT AND STYLE MANUAL
4.4 Units and Quantities
Units
In recognition of the international use and applicability of API standards, measured and calculated values
should be expressed in metric (SI) units and U.S. customary (USC) units. When citing units in dual units,
the SI unit should be listed first, with the corresponding USC unit listed either in parentheses in the text or
on separate tables, figures, or datasheets, or in separate annexes. When dual units are used, the same
order for the units shall be used throughout the document.
Do not use periods within units [pounds (lb), feet (ft), seconds (s), hours (h), minutes (min), year (yr)].
The exception to this is inches (in.). See API MPMS Ch. 15 for guidelines on the API-preferred units for
quantities involved in the petroleum industry.
Quantities
The following rules should be observed:
a) For numbers between -1.0 and 1.0, a zero shall be placed in front of the decimal (e.g. 0.0525).
b) For clarity, the symbol × shall be used to indicate multiplication rather than a dot ( • ).
c) In general text, isolated number less than 10 shall be spelled out. However, in equations, tables,
figures and other display elements numerals should be used.
d) The value of a quantity is expressed by a numeral followed by a space and the appropriate unit
symbol.
e) If tolerances are provided, the unit shall be given with both the basic value and the tolerance (e.g.
1 mm ± 0.05 mm);
f)
Ranges should repeat the unit (e.g. 2 psi to 12.5 psi, 0 mph to 6 mph).
NOTE Dashes should not be used since they can be misinterpreted as subtraction signs.
g) The abbreviation for inches shall include a period (in.) to avoid confusion with the word “in.”
h) Units shall be spelled out when not used with a number (“...2 gal/min” vs “...they are measured in
gallons per minute.”)
4.5 Digitization
As industry moves from “narrative-based” type standards to requirement-based documents that will allow
for a transition to digitization, standards-developing organizations and the subject-matter experts who
develop industry standards should exhibit care in ensuring a requirement is appropriately crafted.
Characteristics of requirements statements are covered in Table 5.
API DOCUMENT FORMAT AND STYLE MANUAL
7
Table 5-Characteristics of Requirement Statements
Characteristic
Definition
Rules
Necessary
Adds specific value to
Does this prevent a major accident or reduce major accident
business delivery. If not
risk?
included, a deficiency in
Can this prevent a fatality?
capability will exist that
Does this prevent a safety incident?
cannot be fulfilled by
implementing other
What would happen if this was removed from our practice, i.e.
requirements.
what would be the impact on safety, reliability, operational
performance, lifecycle reliability?
Does this make industry more competitive and improve
sustainability?
Is it personal preference? Reference to an internal
organization or role may indicate this.
Feasible
Can be realized within
Can this requirement be implemented?
known constraints (e.g.
Is this requirement applicable in all cases?
cost, schedule, technical,
legal, regulatory) with
acceptable risks. Avoid
aspirational requirements.
Verifiable
Structured and worded
Each requirement has a precise and verifiable outcome.
such that its realization can
Avoid non-specific terms, e.g. “readily,, “clearly,” “proven,” or
be proven (verified) to the
“early life.” If a term is not defined precisely, risk and cost may
customer’s satisfaction.
increase, particularly if the requirement is used in a contract.
Unique
Requirements cannot
Is it repeated elsewhere?
contradict or repeat other
In terms of the specification, is the requirement global, or
requirements in your
specific, e.g. to an item of equipment, environment, or asset? If
requirements architecture.
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?
Subject
The single thing to which
the requirement
refers. This can include the
function, person, system,
or sub-system.
Singular
State a single capability,
A single requirement reduces ambiguity and conflict. It is also
characteristic, constraint,
essential for digitalization, where verification, information, and
or quality factor. A good
attributes are linked to requirements.
requirement has a single
Each requirement usually has one “shall” statement. There
requirement. Avoid use of
may be two “shalls” if they relate to one requirement, but this
“and”.
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, e.g. “The system shall contain the following:”
and then list 10 different independent “shall” requirements.
Lists are acceptable in other circumstances, e.g. listing
options: “The system shall meet one of the following:” then
list some options or list a set of closely related aspects
that need to be met to achieve one requirement.
8
API DOCUMENT FORMAT AND STYLE MANUAL
Characteristic
Definition
Rules
Unambiguous
Clear and concise
Avoid complex sentences 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. Guidance for the number of words per sentence
is 25. More than this is OK, but clarity should be checked.
Additional guidance is that if a user needs to read a sentence
twice to understand it, the sentence needs to be rewritten.
Conditional construct (if, for, etc.) should be avoided if
possible. If conditional construct is used, the condition should
be at the beginning of the sentence. If 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, such as “a,” “all,” “any,” each,”
“every,” or “the”.
Examples before:
Every high-voltage switching device shall have sets of
volt-free auxiliary contacts.
Any main circuit hardware or equipment that is
withdrawable shall be fitted with a panel number
locator label.
Examples after:
High-voltage switching devices shall have sets of volt-
free auxiliary contacts.
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.
[REFERENCE: INCOSE-TP-2010-006-2, INCOSE Guide for Writing Requirements, Rev. 2, as amended for API.]
4.6 Page Proof Review Guidelines
Typical time for page proof review based on API’s Editorial Complexity Formula is as follows:
- Level 1 standards: those with up to 10 figures, up to 10 tables, up to 10 equations, and up to
50 pages-7 to 10 business days
- Level 2 standards: those with 10 to 20 figures, 10 to 20 tables, 10 to 20 equations, and 50 to
150 pages-11 to 14 business days
- Level 3 standards: those with
20+ figures,
20+ tables,
20+ equations, and
150+ pages-
15 to 21 business days.
Page proof reviews should be conducted by the standard’s subcommittee, task group, or work group
leadership in conjunction with the standard’s master editor if one exists.
API DOCUMENT FORMAT AND STYLE MANUAL
9
5 Document Structure
5.1 General
Final formatting is performed by API staff before publication; therefore, it is unnecessary for a committee
to make the document look like a published document. However, the amount of staff effort required to
prepare the document for publication can be reduced if the committee adopts the proper numbering
format when the draft is prepared.
5.2 Normative and Informative Text
Normative text denotes information that is required to implement the document. Informative text is
provided for information only.
The document shall contain normative text in the main sections of the document, including footnotes to
tables (see Annex B), and in normative annexes. Informative text should be placed in notes (to text,
tables, and figures), in footnotes within text, and in informative annexes.
5.3 Subdivision of Subject Matter
Descriptions of Divisions and Subdivisions
Terms to be used to designate the divisions and subdivisions of a document are shown in Table 5.
Table 6-Names of Divisions and Subdivisions
Term
Example of Numbering
Part
9999-1
Section
1
Subsection
1.1
Subsection
1.1.1
Paragraph
(no number)
Annex
A
Part
An individual document shall be prepared for each subject to be standardized and published as a
complete entity. However, in specific cases and for practical reasons, the document may be split into
separate parts under the same number if, for example:
a) the document is likely to become too voluminous,
b) subsequent portions of the content are interlinked,
c) portions of the document could be referred to in regulations, or
d) portions of the document are intended to serve for certification purposes.
This has the advantage that each part can be changed separately when the need arises. In particular,
the aspects of a product which will be of separate interest to different parties (e.g. manufacturers,
certification bodies, legislative bodies) shall be clearly distinguished, preferably as parts of a document or
as separate documents.
Such individual aspects are, for example,
- health and safety requirements,
10
API DOCUMENT FORMAT AND STYLE MANUAL
- performance requirements,
- maintenance and service requirements,
- installation rules, and
- quality assessment.
The terms used to designate the divisions and subdivisions that a document may have are shown in
Table 1.
Section
A section is the basic component in the subdivision of the content of a document. The sections in each
document or part shall be numbered with Arabic numerals, beginning with 1 for the “Scope” section. The
numbering shall be continuous, up to but excluding any annexes.
Each section shall have a title, placed immediately after its number, on a line separate from the text that
follows it.
Subsection
A subsection is a numbered subdivision of a section. A primary subsection (e.g. 5.1, 5.2, etc.) may be
subdivided into secondary subsections (e.g. 5.1.1, 5.1.2, etc.), and this process of subdivision may be
continued as far as the fifth level (e.g. 5.1.1.1.1.1, 5.1.1.1.1.2, etc.). Subsections within the document are
not referenced as “Section X.X,” unless the reference is to a subsection of a different document (e.g.
“See 5.2 of this document for more information, or reference ASME BXX.X-Section 6.1”); however,
whole sections are always referenced (e.g. “See Section 5 of this document for more information, or
reference ASME B13.1-Section 6.1”).
A subsection shall not be created unless there is at least one further subsection at the same level. For
example, text in Section 10 shall not be designated subsection “10.1” unless there is also a subsection
“10.2.”
Each primary subsection should preferably be given a title, which shall be placed immediately after its
number, on a line separate from the text that follows it. Secondary subsections may be treated in the
same way. Within a section or subsection, the use of titles shall be uniform for subsections at the same
level (e.g. if 10.1 has a title, 10.2 shall also have a title). In the absence of titles, key terms or phrases
(composed in distinctive type) appearing at the beginning of the text of the subsection may be used to
call attention to the subject matter addressed. Such terms or phrases shall not be listed in the table of
contents.
Subheadings that are not numbered should be in title case and followed by an em dash (-), and the first
word after the em dash should be capitalized.
EXAMPLE
Conventional Methods-The vast majority of inspections...
Paragraph
A paragraph is an unnumbered subdivision of a section or subsection.
Hanging paragraphs, such as those shown in Table 6, shall be avoided since reference to them is
ambiguous.
API DOCUMENT FORMAT AND STYLE MANUAL
11
Table 7-Examples of Hanging Paragraphs
Incorrect
Correct
5 Designation
5 Designation
The quick brown fox jumps over the lazy dog.
5.1 General
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
5.1 Xxxxxxxxxxx
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
5.2 Xxxxxxxxxxx
5.2 Xxxxxxxxxxx
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
5.3 Xxxxxxxxxxx
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The
quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog. The
quick brown fox jumps over the lazy dog.
6 Test Report
6 Test Report
NOTE The hanging paragraphs indicated cannot be uniquely identified as being in Section 5 since, strictly speaking, the
paragraphs in 5.1 and 5.2 are also in Section 5. To avoid this problem, it is necessary to identify the unnumbered
paragraphs as subsection “5.1 General” (or other suitable title) and to renumber the existing 5.1 and 5.2 accordingly (as
shown), to move the hanging paragraphs elsewhere, or to delete them.
Annex
5.3.6.1
General
Annexes, if included, shall appear in the order in which they are cited in the text unless a document with
existing annexes is under revision, and in which case, any new annexes may be inserted after the
existing annexes even if this is not the order in which they are cited in the text. Each annex shall be
designated by a heading comprising the word “Annex,” followed by a capital letter designating its serial
order, beginning with “A”; e.g. “Annex A”. The annex heading shall be followed by the indication
“(normative)” or “(informative),” and by the title, each on a separate line. Numbers given to the sections,
subsections, tables, figures, and mathematical equations of an annex shall be preceded by the letter
designating that annex, followed by a full stop. The numbering shall start anew with each annex. A single
annex shall be designated “Annex A”.
EXAMPLE Sections in Annex A are designated “A.1”, “A.2”, “A.3”, etc.
5.3.6.2
Normative Annexes
Normative annexes, if included, give provisions additional to those in the body of the document. An
annex’s normative status (as opposed to informative-see 5.3.6.3) shall be made clear by the way in
which it is referred to in the text, by an indication in the table of contents, and under the heading of the
annex.
5.3.6.3
Informative Annexes
5.3.6.3.1 Informative annexes, if included, give additional information intended to assist the
understanding or use of the document. They shall not contain requirements, except as described in
5.3.6.3.2. An annex’s informative status (as opposed to normative-see 5.3.6.2) shall be made clear by
the way in which it is referred to in the text, by an indication in the table of contents, and under the
heading of the annex.
12
API DOCUMENT FORMAT AND STYLE MANUAL
5.3.6.3.2 Informative annexes may contain optional requirements. For example, a test method that is
optional may contain requirements, but there is no need to comply with these requirements to claim
compliance with the document.
Bibliography
A bibliography, if present, shall appear after the last annex. See 6.6.9 for additional information.
6 Document Elements
6.1 Lists
Lists in a subsection may be ordered (prefixed by a number or a letter) or unordered (not prefixed by a
number or a letter); however, ordered lists are recommended to facilitate ease of reference. An ordered
list of items within a subsection should be presented in outline form, with items lettered a), b), c), etc. If a
further subdivision of the items is necessary, 1), 2), 3); i), ii), iii); dashed subdivision items; etc., should be
used to form a tiered list.
If possible, only one ordered list may be presented in any subsection to avoid confusing cross-
references. A dashed lists can be used instead of an ordered list, where applicable. However, if inclusion
of more than one ordered list within a subsection is necessary, with text introducing each list, the
separate lists shall have different sets of numbers or letters prefixing each list; e.g. items within the first
ordered list are numbered 1), 2), 3), and within the second ordered list a), b), c) or 4), 5), 6). Under no
circumstances shall letters or numbers prefixing separate ordered lists within the same subsection have
the same numbers or letters.
Bullets (•) shall not be used in unordered lists, to avoid confusion with bullets used to denote a
purchaser's decision (see 6.6.7.2).
Annex C provides examples of ordered and unordered lists.
6.2 Tables
Usage
Tables should be used when they are the most efficient means of presenting information in an easily
comprehensible form. All tables shall be referenced in the text of the document. A table within a table is
not permitted. Subdivision of a table into subsidiary tables is not permitted.
See Annex B for details on creating tables.
Designation
Tables shall be designated “Table” and numbered consecutively with Arabic numerals, beginning with 1.
This numbering shall be independent of the numbering of the sections and of any figures. A single table
shall be designated “Table 1”.
Tables included in annexes shall include the identifying letter of the annex in which they appear.
EXAMPLE The first table in Annex A would be identified as Table A.1.
For documents maintained under the continuous-maintenance option, a table may be identified by the
section number preceding the table number, separated by a period.
EXAMPLE Tables in Section 4 of a document would be identified as Table 4.1, Table 4.2, Table 4.3, etc.
API DOCUMENT FORMAT AND STYLE MANUAL
13
6.3 Figures
Usage
Figures should be used when they are the most efficient means of presenting information in an easily
comprehensible form. All figures shall be referenced in the text of the document.
Figures included in annexes shall include the identifying letter of the annex in which they appear.
See Annex D for details on creating figures, including obtaining the necessary permissions.
Designation
Figures shall be designated “Figure” and numbered with Arabic numerals, beginning with 1. This
numbering shall be independent of the numbering of the sections and of any tables. A single figure shall
be designated “Figure 1”.
Figures included in annexes shall include the identifying letter of the annex in which they appear.
EXAMPLE The first figure in Annex A would be identified as Figure A.1.
For documents maintained under the continuous-maintenance option, a figure may be identified by the
section number preceding the figure number, separated by a period.
EXAMPLE Figures in Section 4 of a document would be identified as Figure 4.1, Figure 4.2, Figure 4.3, etc.
6.4 Equations
General
Equations should be presented consistently throughout the document. The equation shall be introduced
with a phrase or sentence, followed by the equation on the next line. The equation shall be followed on
the next line with the list of variables and their definitions in the order in which they appear in the
equation. Units in the equation list that are not grouped with a number should be spelled out with the
abbreviation in parentheses (see Example 1). Sometimes, it is not necessary to spell out the units, in
order to make the list more readable (see Example 2, where both SI units and USC units are shown, and
the units for k are fairly long). The editor should use their best judgment and remain consistent
throughout the document.
EXAMPLE 1
The maximum allowable residual unbalance per plane (journal) shall be calculated as follows:
4W
U
(15)
N
where
U is the unbalance per plane in inches (in.);
W is the load per journal in pounds (lb);
N is the rotative speed in revolutions per minute (r/min).
14
API DOCUMENT FORMAT AND STYLE MANUAL
EXAMPLE 2
For insulated vessels, the environment factor for insulation is given as follows:
In SI units:
k(904T
f
)
F
(A.1)
66,570
ins
In USC units:
k(1660
T
f
)
F
(A.2)
ins
21,000
where
k is the thermal conductivity of insulation at mean temperature, expressed in W/m K
(Btuꞏin./hꞏft2ꞏ°F);
δins is the thickness of insulation, expressed in m (in.);
Tf is the temperature of vessel contents at relieving conditions, expressed in °C (°F).
Numbering
If it is necessary to number some or all of the equations in a document in order to facilitate cross-
reference, Arabic numbers in parentheses shall be used, beginning with 1:
wmax = m1 ∕(m1+ m2 )× 100 %
(1)
The numbering shall be continuous and independent of the numbering of sections, tables, and figures.
Subdivision of equations [e.g. (2a), (2b), etc.] is not permitted. The numbering is permitted to start anew
with each annex.
EXAMPLE Equations in Annex A may be designated “(A.1)”, “(A.2)”, “(A.3)”, etc.
6.5 References
General
References to a particular portion of text should be used instead of repetition of the original source
material. Repetition involves the risk of error or inconsistency and increases the length of the document.
References shall be made in the forms indicated in 6.5.2 through 6.5.4.3, and shall not be made to page
numbers.
References to Elements of Text
Use, for example, the following forms:
API DOCUMENT FORMAT AND STYLE MANUAL
15
- “in accordance with Section 3;”
- “according to 3.1;”
- “as specified in 3.1 b);
- “details as given in 3.1.1;”
- “see Annex B;”
- “the requirements given in B.2;”
- “see the Note in Table 2;”
- see Note 2;
- “see A.6.3, Example 2;”
- “see Item a) above;”
- “repeat Step 4);”
- “see 3.1, Equation (3).”
It is unnecessary to use the term “subsection” or “clause" (see 5.3.4).
References to Figures and Tables
Every figure and table included in the document shall normally be referred to in the text.
Use, for example, the following forms:
- “shown in Figure A.6 and Figure A.7,”
- “(see Figure 3),”
- “given in Table 2,”
- “(see Table B.2).”
References to Other Documents
6.5.4.1
General
All normative references, undated and dated, shall be given in the “Normative References” section (see
6.6.4).
6.5.4.2
Undated References
Undated references may be made only to a complete document and only in the following cases:
a) if it is accepted that it will be possible to use all future changes of the referenced document for the
purposes of the referring document,
NOTE For undated references, the latest edition of the referenced document (including any addenda) applies.
16
API DOCUMENT FORMAT AND STYLE MANUAL
b) for informative references.
Undated references shall be understood to include all amendments to and revisions of the referenced
document.
Use the following forms:
- “...as specified in API 5L and API 5L3..,”
- “...see API 653...”
6.5.4.3
Dated References
Dated references are references to a specific edition, indicated by the year of publication. References to
specific sections or subsections, tables, and figures of another document shall always be dated.
Use the following forms:
- “...evaluate using the methods specified in API MPMS Ch. 13.2, First Edition...” (dated reference to a
published document);
- “...as specified in API 1104, 20th Edition-Table 1...” (dated reference to a specific table in another
published document);
NOTE For documents without an edition number, the year of publication may be used.
6.6 Order of Sections within a Document
Foreword
The foreword shall appear in each document. It shall not contain requirements, recommendations,
figures, or tables. It is a general description of the contents of the document.
The foreword can consist of a specific part and a general part. The specific part (supplied by the
committee) should contain any specific information a committee wants to convey to the public, such as a
statement of significant technical changes from any previous edition of the document or the relationship
of the document to other documents. The general part (supplied by API staff) gives information relating to
the document, such as the committee responsible for preparing the document, the effective date, terms
of use, and contact information to submit suggested revisions.
Introduction
The introduction is an optional informative preliminary element used to give specific information or
commentary about the technical content of the document, and about the reasons prompting its
preparation. When used, the introduction shall not contain requirements
(“shall” statements) or
recommendations (“should” statements).
The introduction shall be on a separate page immediately prior to the page on which the Scope appears.
The introduction shall not be numbered unless there is a need to create numbered subdivisions. In this
case, it shall be numbered 0, with subsections being numbered 0.1, 0.2, etc. Any numbered figure, table,
displayed equation, or footnote shall be numbered beginning with 1.
Scope
This normative element shall appear at the beginning of each document and define without ambiguity the
subject of the document and the aspects covered, thereby indicating the limits of applicability of the
document or particular parts of it. The scope shall not contain requirements (“shall” statements) or
recommendations (“should” statements).
API DOCUMENT FORMAT AND STYLE MANUAL
17
In documents that are subdivided into parts, the scope of each part shall define the subject of that part
only.
The scope shall be succinct so that it can be used as a summary for bibliographic purposes and the API
Publications Catalog (www.api.org/publications).
Normative References
This optional informative element provides a list of the references cited in the document in such a way
that some or all of their content constitutes requirements of the document. It is recommended that
undated references be used unless there are technical reasons why a specific edition must be
referenced. Each dated reference shall include its edition number (or year of publication). The year of
publication shall not be given for undated references.
NOTE References may dated or undated.
The list shall be introduced by the following wording:
“The following documents are referred to in the text in such a way that some or all of their content
constitutes requirements of this document. For dated references, only the edition cited applies. For
undated references, the latest edition of the referenced document (including any addenda) applies.”
Insert the footnote for the address of the referenced organization after the publication number of the first
document of that organization. API references do not require a footnote since this address is always
included in the API Foreword. API references shall be listed first, and subsequent references, if any,
follow in alphabetical order.
The following referenced documents are for example only, to demonstrate how normative references
should be formatted in the section.
API Manual of Petroleum Measurement Standards (MPMS) Chapter 3.2, Standard Practice for Gauging
Petroleum and Petroleum Products in Tank Cars
API MPMS Chapter 4 (all sections), Proving Systems
API MPMS Chapter 14.3, Parts 1 to 4, Concentric, Square-edged Orifice Meters
API Specification 5L, Specification for Line Pipe
API Recommended Practice 520 (all parts), Sizing, Selection, and Installation of Pressure-relieving
Devices in Refineries
ANSI B16.5 1, Pipe Flanges and Flanged Fittings
ASME Boiler and Pressure Vessel Code 2, Section II: Materials
ASME Boiler and Pressure Vessel Code, Section VIII: Pressure Vessels; Division 2: Alternative Rules
ASTM A105 3, Standard Specification for Carbon Steel Forgings for Piping Applications
AWS A5.1 4, Specification for Carbon Steel Electrodes for Shielded Metal Arc Welding
ISO 7-1 5, Pipe threads where pressure-tight joints are made on the threads-Part 1: Dimensions,
tolerances and designation
ISO 261, ISO general-purpose metric screw threads-General plan
18
API DOCUMENT FORMAT AND STYLE MANUAL
NACE RP 0372 6, Method for Lining Lease Production Tanks with Coal Tar Epoxy
U.S. DOT Title 49, CFR Part 192 7, Transportation of Natural and Other Gas by Pipeline: Minimum
Federal Safety Standards
______________
1 American National Standards Institute, 25 West 43rd Street, 4th floor, New York, New York 10036, www.ansi.org.
4 American Welding Society, 550 N.W. LeJeune Road, Miami, Florida 33126, www.aws.org.
5 International Organization for Standardization, 1, ch. de la Voie-Creuse, Case postale 56, CH-1211, Geneva, Switzerland,
6 NACE International (formerly the National Association of Corrosion Engineers), 1440 South Creek Drive, Houston, Texas
77218-8340, www.nace.org.
7 U.S. Department of Transportation 1200 New Jersey Ave, SE, Washington, D.C. 20590, www.dot.gov.
Terms and Definitions
This is an optional normative element providing definitions necessary for the understanding of certain
terms used in the document. Only terms actually used in the document shall be defined. The following
introductory wording shall be used where all terms and definitions are given in the document itself:
“For the purposes of this document, the following terms and definitions apply.”
In the case where terms defined in one or more other documents also apply (e.g. in the case of a series
of associated documents where Part 1 specifies the terms and definitions for several or all of the parts),
the following introductory wording shall be used, altered as necessary:
“For the purposes of this document, the terms and definitions given in... and the following apply.”
Rules for the presentation of terms and definitions are provided in Annex E.
Symbols and Abbreviations
This is an optional element providing a list of the symbols and abbreviations necessary for the
understanding of the document (see E.5.). Only symbols and abbreviations actually used in the
document shall be included in the list. Unless there is a need to list symbols in a specific order to reflect
technical criteria, all symbols should be listed in alphabetical order in the following sequence:
- uppercase Latin letter followed by lowercase Latin letter (A, a, B, b, etc.);
- letters without indices preceding letters with indices, and with letter indices preceding numerical ones
(B, b, C, Cm , C2 , c, d, dext , dint , d1, etc.);
- Greek letters following Latin letters (A, B, ...Z, α, β, ...z, etc.);
- any other special symbols.
Variables are set in Times New Roman/Italic in the equations and when referenced in the text; however,
symbols, numbers, abbreviations, and acronyms are not italicized. Subscripts are only italicized if they
are referenced as a variable. For example, Cx (“x” is a variable) vs Cm (“m” denotes that C is measured in
meters).
API DOCUMENT FORMAT AND STYLE MANUAL
19
For convenience, this element may be combined with the Terms and Definitions element in order to bring
together terms and their definitions, abbreviated terms, symbols, and perhaps units under an appropriate
composite title, e.g. “Terms, Definitions, Abbreviations, Symbols, and Units.”
See E.5 for additional information on symbols and abbreviated terms.
Annexes
Annexes should appear in the order in which they are referenced in the body of the document (see also
5.3.6.1); e.g. the first annex mentioned should be Annex A, the second Annex B, and so on. Note that
this rule means that normative and informative annexes will be intermixed. An exception to this rule is the
bibliography (see 6.6.9). See 5.3.6 for more information on annexes.
Bibliography
6.6.8.1 A bibliography, if present, shall appear after the last annex. The bibliography should include the
following:
a) referenced documents that are cited in an informative manner,
b) referenced documents that are bibliographic or backg3round material in the preparation and
application of the document.
6.6.8.2 If bibliographic items are cited in text, figures, or notes, the citation shall be superscript and
placed in square brackets at the point where reference is made and shall be numbered consecutively;
e.g. [1], but is not superscript when the reference is in the following form: “See Reference [1] in the
bibliography.” Lists of bibliographic references are arranged in numeric sequence corresponding to the
order of citation in the text (e.g. “Single Citation [1],” “Multiple Citations [2, 4, 9 to 22] ”).
NOTE 1
Document titles should be set in italics.
NOTE 2 Names of the months are always spelled out in text, whether alone or in dates.
The following referenced documents are for example only, to demonstrate how documents in the
Bibliography should be formatted.
[1] Robert F. Herbert III, “Can Duplex Stainless Steels Improve the Key Performance Indicators of an
Operating Unit,” Duplex America 2000 Conference, Houston, Texas, Paper DA2 101, March 2000
[2] Ralph M. Davison and James D. Redmond, “Practical Guide to Using Duplex Stainless Steels,”
Materials Performance, January 1990, pp. 57-62
[3] J.M.A. Quik and M. Geudeke, “Switch to Duplex Stainless Steels,” Chemical Engineering
Progress, November 1994, pp. 49-53
[4] Julio G. Maldonado and Russell D. Kane, “Failure Analysis Investigation of Super Duplex
Stainless Steel Tubing,” Stainless Steel World Conference, Paper P0240, Houston, Texas,
February 12-14, 2002
[5] Sandvik Steel Brochure, S-51-51-ENG, Duplex Stainless Steels for Demanding Applications,
December 1993
20
API DOCUMENT FORMAT AND STYLE MANUAL
[6] JIP Prospectus, “Prediction and Assessment of Ammonium Bisulfide Corrosion Under Refinery
Sour Water Service Conditions,” Prepared by Dr. Russell D. Kane and Dr. Michael S. Cayard,
InterCorr International, Inc., Houston, Texas, March 20, 2001,
[7] Cathy Shargay, James Turner, Barry Messer, Deyuan Fan, and William Fort, “Design
Considerations to Minimize Chloride Corrosion in Hydrotreater REACs,” NACE International
Corrosion/2001, Paper 01543, Houston, Texas, March 2001
[8] Bluhm W.C., “Safe Operation of Refinery Flare Systems,” API Proceedings, Vol. 41, 1961, API,
Washington, DC
10 Insert the footnote for the address of the referenced organization after the publication number of the
first document of that organization.
6.6.8.3 Documents already listed in the normative references section shall not be included in the
Bibliography.
6.7 Other Informative Elements
General
There are other informative elements in API documents that are used to assist the reader in
understanding the concepts presented in the document. These include: a) notes, b) examples,
c) cautionary statements, and d) footnotes. These elements shall not contain requirements or any other
information indispensable for the use of the document.
Notes
Explanatory statements may be used in the text for emphasis or to offer informative suggestions about
the technical content of the document. These notes provide additional information to assist the reader
with a particular passage and shall not include mandatory requirements.
Notes shall not contain requirements, instructions, or recommendations; they are informative only.
Guidance: You should be able to delete the note without damaging the validity of the document.
A single note in a section or subsection shall be preceded by “NOTE,” placed at the beginning of the first
line of the text of the note. When several notes occur within the same section or subsection, they shall be
designated “NOTE 1,” “NOTE 2,” “NOTE 3,” etc.
These requirements shall apply to NOTES located in tables (see B.2.4) and figures (see D.3).
Examples and Steps
A single example or step in a section or subsection shall be preceded by “EXAMPLE” or “STEP” placed
at the beginning of the first line of the text of the example. When several examples or steps occur within
the same section or subsection, they shall be designated “EXAMPLE 1 or STEP 1,” “EXAMPLE 2 or
STEP 2,” “EXAMPLE 3 or STEP 3,” etc.
API DOCUMENT FORMAT AND STYLE MANUAL
21
Warning and Cautionary Statements
Warnings call attention to the use of materials, processes, methods, procedures, or limits that have to be
followed precisely to avoid injury or death. Cautions call attention to methods and procedures that may
cause damage to equipment. A warning is more important than a caution. If both are to be written for the
same related section or subsection, the warning shall precede the caution (see the following example).
Warning-Add warning statement here.
Caution-Add caution statement here.
Warnings and cautions should start with a clear instruction, followed with a short explanation (if
necessary). If the warning or caution is of a general nature (and is applicable throughout the text), it
should be placed at the start of the text. This avoids the necessity of repeating the same warning or
caution frequently throughout the text. Warnings and cautions shall not be placed in informative text or
notes. See ISO/IEC Guide 51 for more details regarding the inclusion of safety aspects in standards.
Footnotes
Footnotes to the text give additional information; their use shall be kept to a minimum. A footnote shall
not contain requirements or any information considered indispensable for the use of the document.
Footnotes to tables and figures follow different rules (see B.2.5 and D.4). Footnotes to the text shall be
placed at the foot of the relevant page and be separated from the text by a short, thin, horizontal line on
the left of the page. Footnotes to the text should be distinguished by Arabic numerals, beginning with 1,
followed by one parenthesis and forming a continuous numerical sequence throughout the document: 1),
2), 3), etc. The footnotes shall be referred to in the text by inserting the same numerals, as superscripts,
after the word or sentence in question. In certain cases-for example, in order to avoid confusion with
superscript numbers-one or more asterisks or other appropriate symbols may be used instead: *, **, ***,
etc.; †, ‡, etc. Footnotes in the text shall have a space before the superscript. Furthermore, the footnote
on the bottom-left side of the page should have a tab between the superscript and the text. See the
following example:
EXAMPLE 9
6.8 Use of Trade Names
Generally, it is not acceptable to include proper names or trademarks of specific companies or
organizations in the text of a publication. It is not acceptable to include manufacturer lists, service
provider lists, or similar material in the text of a document.
Where a sole source exists for essential equipment, materials, or services necessary to determine
compliance with the document, it is permissible to supply the name and address of the source in a
footnote or informative annex as long as the words “or the equivalent” are added to the reference.
In connection with documents that relate to the determination of whether products or services conform to
one or more documents, the process or criteria for determining conformity can be standardized as long
as the description of the process or criteria is limited to technical and engineering concerns, and does not
include what would otherwise be a commercial term or proper name.
Wherever a term/phrase appears that is a registered trademark, the following text shall be included as a
footnote:
“This term is used as an example only, and does not constitute an endorsement of this product by API.”
(informative)
Writing Tips
A.1 General
This annex provides guidelines and examples to help maintain consistency in written materials produced
by API committees and staff. It covers some of the common rules; however, it is not meant to be all-
inclusive. The most important point to remember is to be consistent when drafting or revising a
document.
A.2 Capitalization
The full rules of capitalization for English are complicated. The rules have also changed over time,
generally to capitalize fewer terms. It is an important function of English style guides to describe the
complete current rules, although there is some variation from one guide to another. Basic conventions of
capitalization are provided in the following list.
- Capitalize formal names of tests (Charpy Impact Test, Wenner Four-pin Method).
- Capitalize names of conditions, groups, effects, and variables only when definite and specific.
(Group A was the control group; an Age × Weight interaction showed lower weight with age.)
- Capitalize the first word after a comma or colon if, and only if, it begins a complete sentence. For
example, “This is a complete sentence, so it is capitalized.” As a counterexample, “no capitalization
here.”
- Do not capitalize generic names of tests (Stroop color test). “Stroop” is a name, so it remains
capitalized.
- Capitalize nouns before numbers, but not before variables (Trial 2, trial x).
A.3 Hyphenation
A definitive collection of hyphenation rules does not exist. There is a wide range of variation in the use of
hyphens to join compound words. No rules govern all combinations, and the possible combinations are
virtually limitless, so many of them will not be found in a dictionary. General rules to consider are
provided in the following.
- Do not hyphenate common prefixes (posttest; prewar; multiphase; nonsignificant) unless needed for
clarity (preexisting).
- Do not hyphenate foreign, letter, numeral terms (a priori hypothesis; Type A behavior) when the
meaning is clear without it (least squares solution; heart rate scores).
- Do not hyphenate if a noun comes first (a therapy was client centered; results of t tests).
- Hyphenate adjectival phrases (role-playing technique; high-anxiety group; two-way analysis).
- Hyphenate compound adjectives preceding nouns (client-centered therapy, t-test scores) unless the
compound adjective involves a superlative (best written paper).
- Hyphenate if the base is an abbreviation or compounded (pre-UCS, non-college bound).
- Hyphenate if the base word is capitalized or a number (pre-Freudian, post-1960).
- Hyphenate if the words could be misunderstood without a hyphen (re-pair, un-ionized, co-worker).
22
API DOCUMENT FORMAT AND STYLE MANUAL
23
- If in doubt, consult the Merriam-Webster dictionary online (www.m-w.com). Standards change. For
example, “data base” is now “database,” “data sheet” is now “datasheet,” “name plate” is now
“nameplate,” and “life-style” is now “lifestyle.”
A.4 Use of Numbers
The following are general guidelines for the use of numbers in text.
- Spell out numbers that are less than 10, not followed by a unit of measurement, and not grouped with
numbers over 10 (e.g. one-tailed t-test; eight items; nine pages; three-way interaction; five trials; First
Edition; two years).
- Use numerals for numbers 10 and above, or numbers under 10 grouped with numbers 10 and above
(e.g. from 6 to 12 hours of sleep; 20th Edition; 20 years).
- Spell out common fractions and common expressions (e.g. one-half; Fourth of July).
- When a number is at the beginning of a sentence, it is always spelled out. If this rule produces a
result that looks awkward, it may be better to rewrite the sentence to avoid starting with a number.
- Use numerals for exact statistical measures, scores, sample sizes, and sums (e.g. multiplied by 3, or
5 % of the sample). Another example: “We studied 30 subjects, all two-year-olds, and they spent an
average of 1 hr 20 min per day crying.”
- To make plurals out of numbers, add “s” only, with no apostrophe (e.g. the 1950s).
- Use combinations of written and Arabic numerals for back-to-back numbers (e.g. five 4-point scales).
- Use combinations of numerals and written numbers for large sums (e.g. over 3 million people).
- Use a comma in numbers that are ≥ 10,000 (e.g. 5000 items; 12,500 bags).
- Use a non-breaking space between the degrees sign and the number for temperature references
(e.g. 98 °C, 100 °F). Do not use a space between the degrees sign and number when referring to an
angle (e.g. 90° angle).
- Use the percent symbol (%) only with numbers (e.g. 5 %), not with written numbers (e.g. five
percent).
NOTE Use a non-breaking space before the percent sign.
A.5 Common Misuse of Words in English
The following are common misuses of some English words:
- “affect” is usually a verb that means “to influence,” as in: Will bad grammar affect my grade?;
- “criteria” is a plural noun; “criterion” is the singular form of “criteria;”
EXAMPLE “These criteria are...” and “This criterion is...”
- “data” is a plural noun; “datum” is the singular form of “data;”
EXAMPLE “These data are...” and “This datum is...”
- “effect” is usually a noun that means “result,” as in: cause-and-effect relationship;
- to “insure” means that money is paid by an insurance company if the event that is insured against
occurs;
- to “assure” is to convince or promise someone;
24
API DOCUMENT FORMAT AND STYLE MANUAL
- to “ensure” is to do something that will cause a particular result or outcome;
- avoid an isolated use of the word “this,” as in: This is discussed later.
Instead, add a word to specifically indicate what “this” refers to:
- this feature;
- this circuit;
- this problem;
- this approach.
The word “that” properly introduces restrictive sections, while “which” introduces nonrestrictive sections.
A more helpful statement of the rule is:
- use “which,” which is always preceded by a comma, when introducing nonessential information;
- use “that,” never preceded by a comma, when introducing essential information.
EXAMPLE 1 Resistors, which often have pretty color bands, are common elements in electronic circuits. In this
example, “pretty color bands” are irrelevant to the functioning of the circuit or whether resistors are commonly used.
EXAMPLE 2 A resistor that has smoke rising from it is in danger of failing. Here, “that has smoke rising from it”
identifies specific resistor(s) that are essential to the meaning of the sentence.
- “Its” is a possessive form, meaning to own or possess. Some people want to make a possessive
form of it by adding an apostrophe followed by an “s.” However, “it's” is not possessive; it's a
contraction of “it is” or “it has” (the apostrophe means that letters or characters have been omitted).
- “There” refers to a place (indicates where) or can be used as a pronoun that introduces a clause or
sentence; “their” is a plural possessive noun.
EXAMPLE 1 Put your wet gloves over there near the fireplace. (indicates where)
EXAMPLE 2 Their schedules all have Monday, Wednesday, and Friday classes. (possessive)
- The term “and/or” should be avoided and, wherever possible, the statement should be rewritten to
clarify the meaning.
EXAMPLE The statement “nuts, or screws, and/or bolts” can be rewritten to read: “nuts, or screws, or a
combination thereof.”
A.6 Needless Words
Omit needless words. Many words can be omitted from a first draft without affecting the meaning of
sentences. The following italicized words are examples of needless words:
a) definitely proved,
b) orange in color,
c) viable alternative (it is not an alternative if it is nonviable!
d) worst-case maximum possible error,
e) because of the fact that.
(normative)
Tables
B.1 Table Designation
Tables should be given a number and a concise title, and should be cited in the text with the word “Table”
followed by the number. This numbering shall be independent of the numbering of the sections and
figures. A single table shall be designated “Table 1.” See 6.2 for more information.
B.2 Table Headings
The first word in the heading of each column or row shall begin with a capital letter. The units used in a
given column shall be unbolded and indicated under the column heading. Variables, symbols, and
dimensions are also unbolded.
EXAMPLE 1
Linear Density
Inside Diameter
Outside Diameter
Type
μ
d
D
kg/m (lb/ft)
mm (in.)
mm (in.)
As an alternative, when all units are the same, a suitable statement (e.g. “Dimensions in millimeters”)
may instead be placed above the right-hand corner of the table.
EXAMPLE 2
Dimensions in millimeters
Type
Length
Inside Diameter
Outside Diameter
Tables with subheadings shall be presented as shown in Example 3.
EXAMPLE 3
Type
Dimension
A
A
B
C
B.3 Layout
B.3.1 The table title and designation shall be centered horizontally above the table, as shown in the
following example.
Table #-Title
B.3.2 Whenever possible, tables should be organized to fit on a single page. When a table must carry
over for more than one page, complete column headings should be repeated at the top of successive
pages. The table number and title should be repeated at the top of the page as follows:
Table #-Title (Continued)
25
26
API DOCUMENT FORMAT AND STYLE MANUAL
B.4 Notes to Tables
Notes in tables shall be treated independently from notes integrated in the text (see 6.7.2). They shall be
located within the frame of the relevant table and shall precede table footnotes (see the following
example). A single note in a table shall be preceded by “NOTE,” placed at the beginning of the first line
of the text of the note. When several notes occur in the same table, they shall be designated “NOTE 1,”
“NOTE 2,” “NOTE 3,” etc. A separate numbering sequence shall be used for each table.
Notes to tables shall not contain requirements or any information considered indispensable for the use of
the document. Any requirements relating to the content of a table shall be given in the text, in a footnote
to the table, or as a paragraph within the table. It is not necessary that notes in tables are referenced in
the body of the table.
EXAMPLE
Dimensions in millimeters
Type
Length
Inside Diameter
Outside Diameter
A
l1a
d1
B
l2
d2 b c
A paragraph containing a requirement.
NOTE 1 Table note.
NOTE 2 Table note.
a Table footnote.
b Table footnote.
c Table footnote.
Footnotes to Tables
Footnotes to tables shall be treated independently from footnotes to the text (see 6.7.5). They shall be
located within the frame of the relevant table, and shall appear at the foot of the table (see the example
in B.2.4).
Footnotes to tables shall be distinguished by superscript lowercase letters, beginning with “a”. The
footnotes shall be referred to in the table by inserting the same superscript lowercase letter.
Footnotes to tables may contain requirements.
(normative)
Lists
Lists may be introduced by:
a) a full sentence ending in a period (see Example 1) and completed by the items in the list that are full
sentences and end in periods;
b) a complete grammatical proposition followed by a colon (see Example 2) and completed by the
items in the list that begin with a lowercase letter and end in a semicolon or comma (except for the
last item); if there are commas within the list;
c) the first part of a proposition followed by a colon (see Example 3) and completed by the items in the
list that begin with a lowercase letter and end in a semicolon or comma (except for the last item).
Each item in a list shall be preceded by a dash or, if necessary for identification, by a lowercase letter
followed by a parenthesis. If it is necessary to subdivide further an item in the latter type of list, Arabic
numerals followed by a parenthesis shall be used (see Example 1).
EXAMPLE 1
The following basic principles shall apply to the drafting of definitions.
a) The definition shall have the same grammatical form as the term:
1) to define a verb, a verbal phrase shall be used;
2) to define a singular noun, the singular shall be used
b) The preferred structure of a definition is a basic part stating the class to which the concept belongs,
and another part enumerating the characteristics that distinguish the concept from other members of
the class.
c) The definition of a quantity shall be formulated in accordance with the provisions of ISO.
EXAMPLE 2
No switch is required for any of the following categories of apparatus:
— apparatus having a power consumption, not exceeding 50 W, measured 2 min after the application of
any of the fault conditions;
- apparatus intended for continuous operation.
EXAMPLE 3
Vibrations in the apparatus may be caused by:
— unbalance in the rotating elements,
- the rolling bearings, and
- aerodynamic loads.
To aid comprehension, it may be preferable not to continue a sentence after the end of the type of list
given in Example 3. Key terms or phrases may be composed in distinctive type to call attention to the
subject matter dealt with in the various list items (see Example 1). Such terms or phrases shall not be
listed in the table of contents; if it is necessary that they be included in the table of contents, they shall
not be presented as list items, but as subsection titles.
27
(normative)
Figures
D.1 General
Figures may be graphs, charts, diagrams, schematic drawings, or photographs. All figures shall be called
out (referred to) in the text of the document. See 6.3 for more information.
D.2 Permissions
Figures should be original and specifically created by the standards drafting group for the API standard.
In the instance that figures are being used in the standard that have been previously published (licensed)
in other sources, permission shall be obtained from an individual having the authority and rights to grant
API a nonexclusive, perpetual, irrevocable, royalty-free worldwide license to use, copy, publish, and
otherwise display the figure.
New licensed figures shall not be published without having a completed permission form submitted.
Licensed figures shall not (1) contain any process or product protected by patent rights, or (2) infringe on
the rights of third parties or contain any information that is unlawful, libelous, or violative of any person's
right to privacy and/or publicity.
D.3 Layout
D.2.1 The figure designation and title shall be centered horizontally below the figure. Textual descriptions
should be replaced by item references and explained in a key, or figure footnote, depending on their
content. In graphs, labeling on the axis should not be replaced by item references to avoid any confusion
between the number representing the item reference and a number representing a value on the axis.
Labeling of curves, lines, etc., on the graphs should be replaced by item references.
D.2.2 When a figure is continued over several pages, it may be useful to repeat the figure designation,
followed by the title and by “(Continued)”, as in the following example:
Figure #-Title (Continued)
Any statements concerning units shall be repeated on all pages after the first, where applicable.
D.2.3 Font type should be Arial and font size should be as follows:
a) statement containing units-9 pt,
b) table text-9 pt (header row should be in bold font),
c) key (heading should be in bold font)-9 pt,
d) notes and paragraphs containing requirements-9 pt,
e) subtitles-10 pt and bold,
f)
footnotes to the figure-9 pt (superscript-8 pt).
D.4 Notes to Figures
Notes to figures shall be treated independently from notes in the text (see 6.7.2). They shall be located
immediately above the figure title and shall precede figure footnotes.
28
API DOCUMENT FORMAT AND STYLE MANUAL
29
A single note in a figure shall be preceded by “NOTE” and placed at the beginning of the first line of the
text of the note. When several notes occur in the same figure, they shall be designated “NOTE 1”, “NOTE
2”, “NOTE 3”, etc. A separate numbering sequence shall be used for each figure (see Table 1).
Notes to figures shall not contain requirements or any information considered indispensable for the use
of the document. Any requirements relating to the content of a figure shall be included in the text, in a
footnote to the figure, or as a paragraph between the figure and its title. It is not necessary to reference
notes to figures.
D.5 Footnotes to Figures
Footnotes to figures shall be treated independently from footnotes to the text (see 6.7.5). They shall be
located immediately above the figure title. Footnotes to figures shall be distinguished by superscript
lowercase letters, beginning with “a”. The footnotes shall be referred to in the figure by inserting the same
superscript lowercase letter (see Figure 1).
Footnotes to figures may contain requirements.
EXAMPLE
(normative)
Drafting Terms and Definitions
E.1 General
A definitions section, typically Section 3 (unless the document does not contain references), is provided
for those not familiar with the terminology in question. Definitions should appear in alphabetical order and
the term defined should be written out completely. Each term should be numbered as a subsection of the
definitions section.
Each definition should be a brief, self-contained description of the term in question, and shall not contain
any other information, such as requirements and elaborative text. The term should not be used in its own
definition.
The form of a definition shall be such that it can replace the term in context. Additional information shall
be given only in the form of examples or notes (see E.4.3).
E.2 Choice of Concepts to be Defined
Any term that is not self-explanatory or commonly known and that can be differently interpreted in
different contexts shall be clarified by defining the relevant concept.
Common dictionary or current technical terms shall be included only if they are used with a specific
meaning in the relevant context.
Trade names (brand names) and archaic and colloquial terms shall be avoided.
Obsolete terms may be included after the preferred term, but their nature shall be indicated (see E.4.2).
E.3 Avoidance of Duplications and Contradictions
Before a term and a definition are established for a concept, it should be determined that no other term
and definition for that concept exist in another recognized industry standard.
If the concept is used in several documents, it should be defined in the most general of those documents,
or in an independent terminology document. The other documents should then refer to this document,
without repeating the definition of the concept.
E.4 Presentation
Layout
The preferred term (set in bold type) shall be placed on a new line, after its reference number, starting
with a lowercase letter (except for any capital letters required by the normal written form in running text).
The definition shall be placed on a new line, as shown below.
3.2
administrative controls
Procedures intended to ensure that personnel actions do not compromise the overpressure protection of
the equipment.
Synonyms
The preferred term (set in bold type) shall be followed by the nonpreferred term on a new line (set in
normal type), as shown below.
30
API DOCUMENT FORMAT AND STYLE MANUAL
31
3.14
burning velocity
flame velocity
Speed at which a flame front travels into an unburned combustible mixture.
Obsolete or superseded terms (set in normal type) shall each be placed on a new line, after the preferred
term (set in bold type), and shall be followed by an indication of their status in parentheses.
5.38
radix
base (obsolete)
Positive integer by which the weight of any digit place is multiplied to obtained the weight of the digit
place with the next higher weight.
Examples and Notes
Examples of term usage and notes concerning entries shall be presented as shown.
EXAMPLE 1 inserted text
3.1.122
riser system
Comprises the riser and all integrated components including subsea and surface equipment.
NOTE In tubing hanger mode, the system includes all components from tubing hanger to the top drive; in tree
mode, the system includes all components from the wellhead to the top drive.
EXAMPLE 2 inserted text
3.1.86
lower marine riser package
LMRP
Upper section of a two-section subsea BOP stack consisting of the hydraulic connector, annular BOP,
ball/flex joint, riser adapter, jumper hoses for the choke, kill and auxiliary lines and subsea control
modules.
NOTE The LMRP interfaces with the BOP stack.
E.5 Acronyms, Abbreviations, and Symbols
General
E.5.1.1 This subsection applies to abbreviations and symbols only. If the document makes extensive use
of abbreviations or symbols, subsection(s) within the definitions section may be provided. If acronyms,
abbreviations, and symbols are included in the definitions section, the section title should be “Terms,
Definitions, Abbreviations, and Symbols.” Subsections 3.1, 3.2, and 3.3 would be titled “Terms and
Definitions,” “Abbreviations,” and “Symbols” respectively.
E.5.1.2 The abbreviations and symbols subsection is not meant to take the place of the definitions
section. If a definition is needed, the term should be added to the definitions section, as well.
Abbreviations followed by the full term only should be listed in alphanumeric order.
E.5.1.3 Technical abbreviations should be used to save time and space, but only if their meaning is
unquestionably clear to the reader. The first use should be spelled out, followed by the abbreviation or
acronym itself in parentheses. The abbreviation does not need to be spelled out in the definitions section
[see E.4.3, Example 2, where BOP (blowout preventer) is not spelled out], unless it is only referenced in
that section (e.g. if BOP is only referenced in this definition and not elsewhere in the document, it would
be spelled out after first use in the definitions section) (see Example below). SI and USC units are not
considered abbreviations and should not be included in a list of abbreviations and acronyms.
32
API DOCUMENT FORMAT AND STYLE MANUAL
EXAMPLE
3.1.86
lower marine riser package
LMRP
Upper section of a two-section subsea blowout preventer (BOP) stack consisting of the hydraulic
connector, annular BOP, ball/flex joint, riser adapter, jumper hoses for the choke, kill and auxiliary lines
and subsea control modules.
The LMRP interfaces with the BOP stack.
Layout
The acronym or abbreviation shall be placed on the left-hand side, and the definition shall be on the
same line, with adequate spacing between the acronym/abbreviation and the definition. The definition
shall be listed in lowercase letters, except for any capital letters required by the normal written form in
running text.
EXAMPLE
3.2
Acronyms and Abbreviations
CFR
Code of Federal Regulations
LFL
lower flammable limit
MAWP
maximum allowable working pressure
NEC
National Electric Code
TLP
tension leg platform
(normative)
Use of Bullets to Indicate Purchaser Decision
A bullet (•) in the margin at the beginning of a subsection or paragraph can be used to indicate that either
a decision is required or further information is to be provided by the purchaser. This information should
be indicated on the datasheet(s), otherwise it should be stated in the quotation request or in the order.
Each bulleted item in the text should have a provision in a datasheet for the purchaser’s decision. The
datasheet item does not require a bullet in the text. Items on the datasheet that require the purchaser to
read the text in order to make a decision or to allow him to find additional technical information on the
item should include a reference to the applicable numbered paragraph.
Bullets appear when the wording “when specified,” “if specified,” or “the purchaser will specify” appears in
the paragraph. A bullet is not required for “unless otherwise specified” or when a decision has been
previously made and the phrase “when XXX has been specified” is used.
In order to indicate to the user the special meaning of the margin bullet, the following text shall be
included in the Introduction of all documents using bullets:
“A bullet (•) at the beginning of a subsection or paragraph indicates that either a decision is required or
further information is to be provided by the purchaser.”
Optionally, the following phrase can be added for the purpose of relating bulleted provisions to
datasheets or orders: “This information should be indicated on the datasheet(s), otherwise it should be
stated in the quotation request or in the order.”
33
Bibliography
[1]
API Procedures for Standards Development
[2]
API Manual of Petroleum Measurement Standards (MPMS) Chapter 15, Guidelines for the Use of the
International System of Units (SI) in the Petroleum and Allied Industries
[3]
ISO/IEC Directives, Part 2 1, Rules for the structure and drafting of International Standards
[4]
ISO/IEC Guide 51, Safety aspects-Guidelines for their inclusion in standards
1 International Organization for Standardization, Chemin de Blandonnet 8, CP 401, 1214 Vernier, Geneva, Switzerland,
|