3. Developing Standards Text
This chapter provides guidance on developing text for The Open Group Standards.
3.1. Normative versus Informative
Most standards contain two classes of information:
-
Normative information is information that the standard defines for the purposes of determining conformance
A standard must include normative information. It may include both mandatory and optional parts.
-
Informative information is provided as explanation and guidance
It does not form part of the standard for the purposes of conformance. In the event of contradictions between normative and informative information, the normative information is always definitive.
Normative information describes the requirements to implement the standard and is therefore officially part of the standard. Informative information is non-binding and not part of the standard.
It is important to separate clearly the normative and informative parts of the standard. This can either be done physically, by creating separate chapters or appendices, or typographically by means such as distinct fonts or the use of shading. Where possible, informative text should be confined to front matter, footnotes, notes, and appendices.
3.2. Dependencies
An important area to take into consideration is that of inter-standard and intra-standard dependencies. Many standards have external dependencies on other standards. Care must be taken to ensure that these are clearly spelled out. In addition, there is a need to ensure that the external standard does not change in such a way that it fails to meet the requirements. This can be achieved by making references to specific versions of external standards, rather than to generic standard titles.
Internal dependencies can be created as a result of optional parts of the standard. Care must be taken to ensure that the optional parts are clearly marked as such, and that there are not dependencies to optional functionality embedded within required parts of the standard.
The preferred way for a standard to refer to itself is to use “this document”. [Source: ISO Training]
3.3. Required Chapters and Sections
The first two chapters – Chapter 1: Introduction and Chapter 2: Definitions – are required to be present in all standards published by The Open Group. This is part of ensuring that The Open Group Standards can be accepted by ISO/IEC. A brief description of these chapters follows.
3.4. Chapter 1: Introduction
Section 1.1: Objective
This section should contain a brief statement of the objective of the standard.
Section 1.2: Overview
This section should describe the scope, context, etc. This section should not contain an overview of the contents of the document – you should use the “This Document” section of the Preface for that purpose.
Section 1.3: Conformance
This section identifies expected criteria for conformance to the standard. It is required in all standards. In all cases it is for guidance only; definitive conformance requirements are given in the relevant certification documentation. If there are no conformance criteria, use the following text: “For the purposes of this standard, no conformance requirements apply.”
Section 1.4: Normative References
This section is required for standards intended to be submitted as a PAS Submission to ISO/IEC JTC 1. Normative references are those documents that contain material that must be understood and used to implement the standard. Note that normative references need to be standards. If there are no normative references, state “None.”.
Section 1.5: Terminology
Users of The Open Group Standards need to be able to identify the requirements they are obliged to satisfy in order to claim compliance with the standard. The users also need to be able to distinguish requirements from other types of provision where there is a choice (i.e., recommendations, permissions, possibilities, and capabilities).
The Open Group Standards contain a terminology section, and the terms used within that section should be used to express requirements and options in the standard.
It is essential to follow rules for expressing provisions of the standard so that a clear distinction can be made between requirements, recommendations, permissions, possibilities, and capabilities.
The meanings specified for the words shall, should, and may are mandated by ISO/IEC directives.
The following is guidance on how to interpret the meaning of the terms by providing equivalent expressions:
-
Shall: is to, is required to, it is required that, only … is permitted, it is necessary
-
Shall not: is not allowed [permitted] [acceptable] [permissible], is required to be not, is required that … be not, is not to be
-
Should: it is recommended that, ought to
-
Should not: it is not recommended that, ought not to
-
May: is permitted, is allowed, is permissible
-
Need not: it is not required that, no … is required
-
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
Section 1.6: Future Directions
This indicates the known future directions for the standard. The default is “None.”.
3.5. Chapter 2: Definitions
This section provides guidance on creating terms and definitions for The Open Group Standards. The Open Group Standards contain terms and definitions in Chapter 2, Definitions.
3.5.1. Most Words Need no Definition
There is no need to define a term if the dictionary definition as defined by the Merriam-Webster’s Collegiate Dictionary suffices.
If an English-speaking reader (using the Merriam-Webster’s Collegiate Dictionary as needed) would interpret a word in its intended sense, there is no need to define it. If the Merriam-Webster’s Collegiate Dictionary offers several meanings for a word, and only one of those meanings conveys your intent, be sure that the rest of the sentence drives the reader to that particular meaning.
3.5.2. Alphabetical Order
Definitions should normally appear in alphabetical order and the term defined should be written out completely and should not be inverted (e.g., “Application Platform” rather than “Platform, Application”).
3.5.3. Self-Contained Definition
Each definition should be a brief, self-contained description of the term in question and shall not contain any other information, such as requirements, elaborative text, or prescriptions on how the term is to be used.
3.5.4. Term not Used in its Own Definition
A term should not be used in its own definition.
3.5.5. Cross-References
Cross-references should occur after the definition. “See:” refers to a term where the desired definition can be found. “See also:” refers to a related term.
3.5.6. Citing External Definitions
If an external standard meeting the standards adoption criteria has a meaning suitable for use, we should use the same definition and cite the source.
3.5.7. Notes on Definitions
As with all writing, the meaning of each statement should be unambiguous. If multiple readers interpret a statement differently, then it is likely that something should be changed.
For advice on the writing style for The Open Group Standards refer to document I801A, The Open Group Technical Publications Style Guide (www.opengroup.org/library/i801a).
It is acceptable to use the online version of m-w.com and official Merriam-Webster’s Collegiate Dictionary applications for definitions rather than the hardcopy Merriam-Webster’s Collegiate Dictionary. (In the event of any discrepancy between sources, definitions from the latter take precedence.)
Forums and Work Groups are strongly encouraged to use definitions that already exist instead of creating new definitions or slightly modifying existing definitions.
Terms defined in other standards may be used in The Open Group Standards as long as they are properly cited, and the standard meets The Open Group Standards Adoption Criteria. Where a term has been adapted, then the citation should note the adaptation (i.e., adapted from ISO/IEC 9945:2009).
A useful technique is to include a General Concepts section within the standard, which can define requirements related to defined terms.
An informative note may be provided to refer the user to another part of the standard or to provide further information inline.
3.5.8. Example Definitions
X. Definitions
For the purposes of this document, the following terms and definitions apply. Merriam-Webster’s Collegiate Dictionary should be referenced for terms not defined in this section.
X.1 Application Architecture
A description of the structure and interaction of the applications as groups of capabilities that provide key business functions and manage the data assets.
Note: Application Architecture is described in Part II, Phase C: Information Systems Architectures – Application Architecture.
X.2 Architecture
-
A formal description of a system, or a detailed plan of the system at component level, to guide its implementation. (Source: ISO/IEC 42010:2007)
-
The structure of components, their inter-relationships, and the principles and guidelines governing their design and evolution over time.
X.3 Architecture Building Block (ABB)
A constituent of the architecture model that describes a single aspect of the overall model. See also Building Block.
3.6. Trademarks
The Open Group trademark statement block provided in a document template should remain unchanged. The Open Group Technical Editor will update it as necessary.
You should make every effort to list other trademark and product attributions used in the document. The general disclaimer text should be used to cover missing attributions:
All other brands, company, and product names are used for identification purposes only and may be trademarks that are the sole property of their respective owners.
Within the document, please adhere to the trademark usage guidelines for all trademarks of The Open Group. If in doubt, refer to www.opengroup.org/legal/trademark.
In particular, note that:
-
A trademark should be used as an adjective, not as a noun
-
A trademark should not be used as a verb
-
A trademark should never be used in the plural form
-
A trademark should not be hyphenated or abbreviated
-
A trademark should not be used in a possessive form