2. Document Structure

The Open Group has a number of publication tracks available (Standards, Guides, White Papers, Case Studies, etc.). Each of these has a template that should be used as a basis for document development (see B. Resources ).

This chapter describes the overall structure of technical documents for publication by The Open Group. This structure is based upon the guidelines contained in Read Me First! A Style Guide for the Computer Industry.

2.1 Front Matter

The document front matter is made up of the following elements.

2.1.1 Title Page

The type of document and its title, and the text "The Open Group".

2.1.2 Copyright Page

Copyright information (see 3.8 Copyright ), together with the type of document, its title, ISBN and document numbers, and contact details for problem reporting.

2.1.3 Contents

Lists parts, chapters, sections (second-level headings), subsections (third-level headings), reference pages, appendices, glossary, and index.

2.1.4 Preface

1. Introduction

   About The Open Group and its document types.

   Note:

   This is boilerplate text which is supplied and maintained by The Open Group editors for all technical documentation published by The Open Group.

2. This Document

   A brief introduction to the document and its purpose. This section may also contain the following subsections:

   • Intended audience, including readership and prerequisite knowledge
   • A brief overview of the document structure
   • Applicability (optional) (e.g., version of software documented)
   • Typographical conventions (e.g., use of fonts and special symbols)
   • History (optional) (e.g., how this document relates to others, rationale or background information for the document, etc.)
   • Problem reporting (optional) (i.e., a contact and method for how to report problems with the software documented or suggestions for improvement)

2.1.5 Trademarks

A full list of trademark acknowledgements for all trademarks used in the document.

Note:

The Open Group trademark block is supplied and maintained by The Open Group editors for all technical documentation published by The Open Group.

2.1.6 Acknowledgements

A list of contributors. Note that The Open Group Standards do not have authors attributed. Other document types may also include an About the Authors page.

2.1.7 Referenced Documents

A list of all documents referenced with full bibliographic details.

To create a reference:

1. Insert a tag, such as C220.
2. Add a bookmark/anchor to the tag.
3. Enter the full text of the referenced document. Ideally, each reference should include the title, author, date, publisher, and document number. Where available, add a URL so that the reader can access the document online.

The preferred style for a document published by The Open Group is:

C220	The TOGAF® Standard, 10th Edition, a standard of The Open Group (C220), published by The Open Group, April 2022; refer to: www.opengroup.org/library/c220

For referenced ISO standards, the tag should include the ISO, ISO/IEC, or ISO/IEC/IEEE standard number only; e.g., ISO/IEC 27031.

When referencing a document authored by more than one person/entity, the format of the tag will be, for example: Josey et al. 2006.

Use the tag in-line to link back to the full definition in this section; for example, "... as defined in the TOGAF Standard [C220]".

A list of related documents can also be included, introduced by text such as: "The following documents are not necessary for implementation of the specification, but provide additional information likely to be of value to implementors or application writers".

2.2 Body Text

Body text is made up of the following elements: chapters, reference pages, appendices, a glossary, and an index.

Each element can include paragraphs, tables, figures, lists, notes, footnotes, and cross-references.

2.2.1 Chapters

Each chapter is an element of a document.

Each chapter covers one main topic. The definition of a topic varies according to the subject matter of the document. Each chapter may consist of numbered sections (second-level headings) and subsections (third-level headings). Fourth-level headings are discouraged. Fifth-level and lower headings must not be used.

The first chapter of a standard developed by The Open Group must include the following:

• Objective or Purpose

  This is a brief statement.

• Overview

  This is an overview of the subject, including the scope, context, etc.

• Conformance

  This identifies expected criteria for conformance to existing standards or the Open Brand. It is required in The Open Group Standards. In all cases, it is for guidance only; definitive conformance requirements are given in certification documentation.

  (This section can be deleted for The Open Group Guides.)

• Normative References

  This section is required for The Open Group Standards intended to be adopted by ISO. 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. This section is optional for other documents, as references are covered in the Referenced Documents section.

  (This section can be deleted for The Open Group Guides.)

• Terminology

  This describes how to interpret the meaning of specific terms. The meanings specified for the words shall, should, and may are mandated by ISO/IEC directives.

  (This section can be deleted for The Open Group Guides.)

• Future Directions

  This describes how the publication and related publications are expected to develop.

The second chapter of a standard developed by The Open Group must contain terms and definitions (see 3.11 Definitions ).

If there are sections or subsections, there should be more than one. A section should have subsections if the subject matter is subordinate to the main theme of the section.

If the restrictions on sections and subsections cannot easily be implemented, consider modifying the structure of the document to obtain a suitable structure within each chapter.

Unnumbered headings can be used to aid readability; they do not appear in the table of contents.

2.2.2 Reference Pages

Reference pages have a special layout (see 4. Reference Pages ). Each page may be contained in a chapter, section, subsection, or in an appendix.

Reference pages must be preceded by a heading and introductory text. The pages should be sorted into alphabetical order.

2.2.3 Appendices

Each appendix is an element of a document.

An appendix contains material that is required for reference, but that would interrupt the flow of information in a chapter; for example, long tables of data. Appendices may contain material that is normative or non-normative; in cases where it is normative, this must be clearly stated.

An appendix may contain sections and subsections, like a chapter. The guidelines about the numbers of sections and subsections are the same as for chapters.

An appendix can also contain reference pages.

Information in appendices can include, but is not limited to, the following:

• Descriptions of data formats and file structures
• Input and output codes; for example, character conversion codes
• Global processing limitations
• Sample files, reports, or programs
• Rationale

2.2.4 Glossary

Brief definitions of terms used in the document. This is optional (though preferred).

For a standard published by The Open Group, the main terms should be in Chapter 2 (Definitions), and only supplementary terms should be provided in a glossary. A glossary is informative.

2.2.5 Index

This is mandatory in standards and guides published by The Open Group.

return to top of page

---

---