Validating against ISO House Style
on
13 Mar 2022
Summary
Metanorma now supports validation of the ISO House Style for ISO deliverables.
Introducing the ISO House Style
ISO and IEC have a comprehensive prescription of the expected style and content arrangement for their standards in ISO/IEC DIR 2.
The rules specified in ISO/IEC DIR 2 are extensive — covering 29 clauses that describe requirements that must be met for a deliverable to be published in either organization. These are requirements applied at the organization level.
This may come as a surprise to some: In ISO, ISO/IEC DIR 2 are not the only requirements!
The ISO Central Secretariat (ISO/CS) has a designated editorial team that assigns every ISO TC/SC with an ISO Editorial Programme Manager (EPM). For those who are familiar with drafting within ISO, the ISO EPM is the editor that performs quality checks and editorial work on submitted drafts.
The lesser known fact is that the ISO/CS editorial team applies an additional set of requirements to deliverables, called the ISO House Style.
The ISO House Style started off as an internal style guide within the ISO/CS editorial team, and was finally published publicly in 2021 to show standards authors what ISO EPMs look for.
The public publication of the ISO House Style excellent in terms of transparency, and more importantly, a boon for standards authors.
Validating against ISO House Style
Since its inception, Metanorma has applied the rules laid out in ISO/IEC DIR 2, to validate ISO and IEC standards authored in Metanorma. The associated warnings are communicated to users during document compilation so that authors.
The intention is to allow the author to fix up any issues early on to prevent downstream problems — ISO standards authors and editors will understand the manual and tedious process of handling comments and resolutions for ballots. One less comment equals plenty of saved time!
In the ISO standards authoring process, the ISO EPM will not comment on your document until the Draft International Standard (DIS) stage.
At DIS stage and onwards, the ISO EPM will take scrutiny on the document, and a standard that does not meet ISO House Style is guaranteed to:
-
be littered with changes made by the ISO EPM that need to be manually tracked (by the author), and
-
accompanied by many ISO/CS comments that every one of them needs responding to.
After which the standards author would be forced to go through the typical comments resolution process:
-
change the document
-
document the change and justifications
-
explain that change
-
host numerous meetings to agree on those changes
Why do this when you can already fix it yourself and save all that time?
Metanorma already performs automatic validation against ISO/IEC DIR 2, for instance:
-
Forewords shall not be subdivided
-
“see” and “refer to” can only introduce informative references.
-
Undated references may be made only to a complete document.
So let’s take it further.
ISO House Style rules validated by Metanorma
General
The ISO House Style contains various rules, some of which can be machine-validated but not all. Metanorma now supports the validation of most, if not all, machine-validatable rules specified in the ISO House Style..
The rules that Metanorma validates for are laid out in ISO content style validation.
Cross-references in the “Terms and definition” clause
Metanorma now validates against the requirements stated in the ISO House Style’s ISO References in Clause 3 (Terms and definitions).
Do not include cross-references in the text to the terminological entries definitions listed in Clause 3. Cross-references to terms and definitions are only included within Clause 3.
Avoid any other cross-references in terms and definitions.
-
Cross-references in terminology clauses can only reference content within terminology clauses.
-
Cross-references outside of terminology clauses can only reference content outside of terminology clauses.
Metanorma validates that the terms clauses and other content are self-contained in cross-referencing.
Lists
Documented in ISO House Style’s Lists section.
If the list comprises several sentences, then use the following list format.
The introductory sentence is a complete sentence and ends with a colon or a full stop.
The list items are complete sentences that start with a capital letter and end with a full stop.
If the list comprises one sentence broken into a list format, then:
the introductory sentence is a partial sentence and preferably ends with a colon;
the list items start in lower case and end with a semicolon (preferred) or a comma, used consistently;
the final list item ends with a full stop.
Metanorma validates against this list structure and content requirements in ISO documents.
List punctuation is also validated to ensure its usage is consistent with that of the sentence preceding it.
Avoid having more than one numbered list in a clause/subclause. If a second numbered list is necessary, insert a new clause/subclause to separate it from the first list or use an unnumbered list.
Metanorma warns if more than one ordered list in a numbered clause is detected.
A list can be subdivided up to four levels. If more levels are required, consider using a table or splitting into several shorter lists.
Metanorma warns if a list is more than four levels deep.
Vocabulary document
The “Vocabulary document” is a special kind of ISO document structure defined by ISO DIR 2 but its requirements have not been documented until the publication of the ISO House Style.
There are several requirements as described by the ISO House Style on Vocabulary documents.
A vocabulary is the only ISO document that can have terminological entries in clauses other than Clause 3. If terminological entries are given in other clauses, use a clause title starting "Terms related to". Terminological entries are never included in annexes.
Metanorma supports the designed behavior:
-
Single terms clause in vocabulary document should have the normal “Terms and definitions” heading.
-
Multiple terms clauses in vocabulary document should be prefixed with “Terms related to”.
Do not include the first line of the fixed text for Clause 3, i.e. "For the purposes of this document, the following terms and definitions apply." This is not needed in a vocabulary document because the terminological entries apply to all the documents of the committee.
Metanorma automatically omits the Clause 3 fixed text for vocabulary documents.
Metanorma has also received clarification from the ISO editorial team that:
-
Symbols and abbreviated terms are preferred to be given as part of terminological entries;
-
Otherwise, symbols and abbreviated terms can be provided in an informative Annex after vocabulary content.
Content
Content in Metanorma is validated according to ISO House Style.
Do not use a hyphen instead of a minus symbol.
The Unicode minus sign, U+2212, should be used instead of the hyphen.
The phrase "and/or" is often used in English to express "either or both" of two options. The meaning can be ambiguous, especially in translation to other languages where the "/" is not a recognized punctuation mark.
Avoid using "and/or" in a document to avoid confusion and misapplication. Use the construction "either x or y, or both" instead.
The conjunction phrase and/or is to be avoided. Metanorma issues a warning if and/or is used.
ISO documents do not use the ampersand (&) in ordinary text. Use the word "and" instead.
The ampersand is to be avoided in ordinary text. Metanorma warns on encountering
the symbol &.
Do not use full stops between letters in abbreviated terms or at the end of clause/subclause headings, table titles, figure titles, normative references or bibliographic entries.
Full stops should be avoided at the end of a title or caption. Metanorma warns on such instances.
Conclusion
Metanorma has implemented automatic validation support for the ISO House Style. This newly implemented functionality is intended to preserve precious time for both ISO deliverable authors, editors and as such for the ISO/CS editing team.
That said, the ISO House Style contains a number of requirements that cannot be automatically validated — we encourage all ISO deliverable authors and editors to familiarize yourself with the new (and growing) style guide!