Style Guidelines

All Engineering Documents should follow the guidelines of the International Organization for Standardization (ISO) Directives with the following exceptions: In the event of a conflict, explicit provisions of SMPTE Operations Manuals and Administrative Guidelines shall prevail. Any variances from the ISO Directives shall be approved by the Director of Engineering or the Standards Vice President.

Particular attention should be given to the following annexes of the ISO Directives, Part 2:

• Annex B, Basic reference works
• Annex C, Example of numbering of divisions and subdivisions
• Annex D, Drafting and presentation of terms and definitions
• Annex E, Drafting of the title of a document

The ISO Directives are available at: http://www.iso.org/directives.

SMPTE Templates

All new Engineering Documents shall use the appropriate, approved SMPTE template. (See Administrative Guideline AG-04 Engineering Document Templates.) This will ensure proper revision management through and including final publication. Document templates can be found in the Standards Community document repository.

Revisions and Amendments

A revision of an Engineering Document may use the original template if the resulting prose is identical to that resulting from use of the current template and the Standards Vice President or Director of Engineering agree to the use of the original publication template.

For a revision of an Engineering Document, the Project Group should start with the Publication Master, which usually can be obtained from SMPTE HQ. The Project Group may, at its discretion, recreate the original document, as published, if an editable master cannot be found. The Project Group is encouraged to follow the ISO Directives but is under no obligation to do so.

An Amendment shall use the current template.

Publication Formats Overview

SMPTE Engineering Documents may be published on paper or in various electronic formats and may comprise one or more separate elements. An Engineering Document always shall include a single prose element and may include other elements such as XML, spreadsheets, media files, and so forth. The collection of elements, regardless of formats employed, is the "Engineering Document" as a whole, and all elements shall be clearly identified in the prose element (see Section Elements). Any change to any element constitutes a change to the Engineering Document. The Project Group and the Technology Committee shall determine the number of elements for publication. The Director of Engineering shall determine the distribution media for all published documents. The format of publication shall alter neither the relevance of, nor the processes that otherwise are required for approval of, an Engineering Document.

Engineering Document Elements may be packaged as one or more Elements using ZIP to facilitate the organization and distribution of the component files.

File Formats for Document Submission

Engineering Documents and other contributed documents shall be submitted to a Technology Committee or its subgroups in a limited set of file formats. The following formats are approved:

Prose and Embedded Tables:

doc and .docx

Engineering Documents should use Office 2007 formats (.docx) for Prose and tabular documents. Engineering Documents may use Office 2003 formats (.doc) as needed. The Project Group shall determine which format to use on a project-by-project basis. Conversions between Office 2003 and Office 2007 formats are not perfect. To minimize the risk of unintended artifacts, conversion between formats is not required.

Adobe Acrobat

(.pdf)

Adobe Acrobat files may be contributed but shall be accompanied by editable files for all the elements in the document (prose, tables, drawings, etc.) to permit further revision.

Spreadsheet:

.xls and .xlsx

The Project Group shall decide which spreadsheet format (.xls or .xlsx) to use for each project. The preferred format is .xlsx.

XML

Any document conforming to W3C Extensible Markup Language (XML) 1.0 (Fifth Edition) or W3C Extensible Markup Language (XML) 1.1 (Second Edition) may be submitted.

The namespaces of all normative XML elements used in XML documents shall have a corresponding normative reference in the prose.

The file extension shall be ".xml", unless otherwise specified by the defining specification of the document or by an appropriate IANA media type registration.

Documents conforming to the following XML-based specifications are specifically allowed:

• W3C XML Schema Part 1: Structures Second Edition (file extension: .xsd)
• W3C Web Services Description Language (WSDL) 1.1
• XML Metadata Interchange (XMI), any Formally Released Version (http://www.omg.org/spec/XMI/)

Drawings:

.vsd, vsdx, .dwg and .emf

Images:

For new projects .jpg, .jpeg, .png, .tif and .tiff are approved image formats. Revisions of existing documents may continue to use .bmp.

Media files:

Any audio, video or image media format documented by SMPTE, whether in an Engineering Document or an RDD, or any other media format that is commonly used, widely available, and appropriate for the user community for which the Engineering Document has been created.

Other non-prose elements:

.txt and program source formats

SMPTE HQ Guidance

The Director of Engineering shall store and process documents in the format chosen by a Project Group and/or Technology Committee. The Director of Engineering shall ensure that copies of the editable source documents are maintained for all published Engineering Documents. The editable publication master should be made available by the Director of Engineering when a Revision or Amendment project is started.

Document Numbering Overview

Document numbers shall be unique and uniform across all Engineering Document types. Versions of documents shall be identified by their year of publication and, optionally, their month of publication, appended with a separating colon (e.g., for document #1020: 1020:2009 or 1020:2009-04, the latter indicating publication in April, 2009). shows an example of the document numbering structure.

The Director of Engineering shall assign document numbers (or root document numbers, in the case of multipart documents). Document numbers may be assigned at the request of the Technology Committee Chair(s) at any time after a Project is approved and shall be assigned before a Final Committee Draft ballot is issued.

Older Engineering Documents may bear one-, two-, or three-digit document numbers or root document numbers. These numbers shall not be prepended with leading zeroes when formatted for printing, either in the document itself or in citations in other documents. Such document numbers shall be prepended with leading zeroes to fill them out to four digits, however, when used as part of an element’s filename; the purpose is to facilitate sorting into numerical order.

Engineering Document Type

The Type of Engineering Document (Standard, Recommended Practice or Engineering Guideline) shall be denoted by prepending a Type Designator, followed by a single space, to the document’s root number. The Type Designator shall be as follows:

Although they are not Engineering Documents, Registered Disclosure Documents, Advisory Notes, Administrative Guidelines, and Engineering Reports shall bear Type Designators as follows:

RDDs and ERs shall be numbered using independent number spaces. The numbers shall be assigned by SMPTE Headquarters staff.

Parts

Closely related Engineering Documents may be created as Parts. A Part of a document is a separate Engineering Document and shall be shown to be related to other documents by using the same root document number plus a suffix of a hyphen and the Part number to distinguish among Parts (e.g. 1020-2:2009, indicating document 1020, Part 2).

Elements

Non-prose Elements of Engineering Documents (see Section Publication Formats and Elements) shall be designated using a lower case letter (e.g. 1020a:2009 and 1020b:2009). Media such as DVDs, as well as non-PDF formats, shall be clearly marked, as appropriate. The single prose element shall not receive a letter suffix.

Number Space

All new Engineering Documents shall share a common root number space, starting with 2000, except for new Parts of multipart documents that have a one-, two- or three-digit root.

In the past, each type of Engineering Document had its own number space. This presented difficulties when a Technology Committee determined that the document type had to be changed (for example, changing a Recommended Practice to a Standard) if the number in the new number space already was in use. To address this going forward, the block of numbers from 1000 to 1999 has been allocated.

If a Technology Committee determines that the classification of an Engineering Document with a one-, two- or three-digit root must be changed (e.g., from a Recommended Practice to a Standard) and there already is an Engineering Document with that number, the document whose classification is being changed shall have 1000 added to its root. For example, if the Technology Committee were to determine that Recommended Practice RP 222 should be changed to a Standard, its number would be changed to SMPTE ST 1222 because there already is a SMPTE ST 222.

Each of the other published document types (i.e., Registered Disclosure Documents, Advisory Notes, Administrative Guidelines, and Engineering Reports) shall have its own number space independent of Engineering Documents and of each other. They otherwise shall follow the rules for document numbering specified in this Administrative Guideline.

Due Process Engineering Documents

File names for due process Engineering Documents should be constructed as follows.

<group> “-“ <state> “-“ <type> “-“ <number> [ “-“ <part> ] [ <element> ] “-“
    <description> “-“ <date> [ “(“ <note> “)” ] “.” <extension>

Where:

<group> is the Group that authored the document (e.g., TC name, “31FS”)

<state> is “WD” | “CD” | “FCD” | “DP”

<type> is “ST” | “RP” | “EG” | “RDD” | “AN” | “ER” | “OV” | “AG” See section Engineering Document Type

<number> is the SMPTE HQ staff-assigned document number

<part> is the optional part number

<element> is the optional element letter

<description> is a brief indicator of subject, such as an abbreviated name of the document, which is constructed using only alpha characters, digits and "-". The description is a required element of the file name.

<date> is the document version date, formatted (“YYYY-MM-DD”) as defined in section Dates.

<note> is an optional string that can be used to annotate the file contents, e.g., “(clean),” “(markup),” “(package),” or similar information. The <note> shall be constructed using only alpha characters, digits, “-“.

<extension> is an approved extension. See section File Formats for Document Submission

The <description> and <note> fields can use CamelCase or hyphens as word separators. The Document Editor and Project Chair need to consider both choices and make a decision based on the project name, any acronyms used, the length of the name and related factors.

Elements That Are One File

The Project Group should follow the recommendation in this section or the requirements in section Document Numbering. The final publication name shall be assigned by the Director of Engineering.

Elements That Are a Collection of Many Files

Elements that are a collection of files shall be aggregated into a single file that is a .zip file. The .zip file may contain other .zip files if necessary. The file name for the .zip file shall follow the rules outlined in section Elements That Are One File. The names of the files in the .zip file shall be at the discretion of the Project Group. The Project Group may use the schemes defined in this AG. They should use a scheme that is appropriate for the files in the element.

File Names for Contributions

File names for contributions that are not Engineering Documents shall be at the discretion of the individual or group making the contribution. The scheme in Section Due Process Engineering Documents should be considered as a useful model. If these rules are used, the <state> should be “C.”

For a new project, the document number and even the project short name may not be known. In this event, individuals making the contributions should use their judgment when naming files.

Document Packages Overview

Various document packages are needed during the development process. In all cases, a document being reviewed or voted upon shall be the current draft which is the “clean” version.

In the event that any of the following is in conflict with the SMPTE Standards Operations Manual, the Operations Manual shall prevail.

Working Draft Development

Section Style and Form of this AG has guidance for the use of templates for new projects, Revisions and Amendments.

For Revisions the process of converting an old document into the current template changes section numbering and alters the appearance of the original document, even though the content of the document has not changed. In this case, it is recommended that the conversion to the current template should be made before any other changes are made. The document editor should “accept all changes” to create a clean starting point (the “baseline draft”) from which to track the technical and/or editorial revisions to the document.

During Working Draft development (an informal process), a Project Group may provide intermediate draft documents and markups for review within the Project Group. Intermediate document packages may include an informal Comment Resolution Record or a Comment Resolution Document.

The state of these draft documents shall be “WD.” Project Groups should follow the recommendations and styles given in this Administrative Guideline for file names.

Pre-Ballot Review Document Package

The first step in the formal document process is the preparation of a Working Draft, which shall be marked as “WD.” This document a package is provided by the Project Group to the Technology Committee Chair(s). This review is optional; See the Standards Operations Manual for guidance.

The document package shall contain a clean draft. In addition it may contain one of the following:

• For new documents, no original work exists, so a markup is not meaningful.
• For a Revision, the Project Group should provide a markup from the published document (the baseline draft) in the template to be used for the revision project.
• For an Amendment, the formal document is the list of changes to be made to the published document. A markup from the published document may be provided at the Project Group’s discretion.
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.

Final Committee Draft Ballot Document Package

Following Pre-Ballot Review, a Project Group should address all comments. See the comment resolution process in the Standards Operations Manual. When the Project Group agrees that the document is ready for ballot, it shall provide a Committee Draft ballot package marked as “CD” to the Technology Committee Chairs(s) that contains:

• A clean version of the Committee Draft document marked as “CD.”
• For a new Engineering Document, a markup from the Pre-Ballot Review draft should be included if any changes have been made.
• For a Revision, a markup from the baseline draft should be included.
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.

When additional Final Committee Draft Ballot(s) are required, the Project Group shall submit a package to the Technology Committee Chair(s) that contains the following:

• A clean version of the Committee Draft document marked as “CD.”
• A markup from the previous ballot may be included.
• For a Revision, a markup from the baseline draft should be included.
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.
• A Comment Resolution Record is required. This should be the electronic comment resolution records kept on the SMPTE web site. In some situations the Project Group may wish to keep other records. See the Standards Operations Manual for guidance.

FCD Ballot Comment Resolution Package

If a document passes Final Committee Draft ballot with no comments, comment resolution, Pre-DP Review and a Draft Publication Vote are not required. See the Standards Operations Manual for guidance.

Incremental Comment Resolution within the Project Group may result in the need for multiple Drafts, Markups, and Comment Resolution Records or Comment Resolution Documents. These document packages shall contain:

• A clean version of the draft document. If the ballot passed, this shall be marked as “FCD.” If the ballot failed, this shall be marked as “CD.”
• A markup from the ballot document should be provided.
• For a Revision, a markup from the baseline draft should be included.
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.
• A Comment Resolution Record is required. This should be the electronic comment resolution records kept on the SMPTE web site. In some situations the Project Group may wish to keep other records. See the Standards Operations Manual for guidance.

When Comment Resolution has been successfully completed, a Pre-DP Review follows. Comment resolution may include one or more Disposition Votes. See the Standards Operations Manual for guidance.

Pre-Draft Publication Vote Review Document Package

Following comment resolution, the Project Group shall provide the Technology Committee Chair(s) a Pre-DP review package that contains:

• A clean version of the current Final Committee Draft document marked as “FCD.”
• A markup from the Final Committee Draft ballot document.
• For a Revision, a markup from the baseline draft should be included.
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.
• A Comment Resolution Record is required. This should be the electronic comment resolution records kept on the SMPTE web site. In some situations the Project Group may wish to keep other records. See the Standards Operations Manual for guidance.

Draft Publication Vote Document Package

Following the Pre-DP Review, the Project Group shall provide the Technology Committee Chair(s) a DP Vote package that contains:

• A clean version of the current Final Committee Draft document marked as “FCD.”
• If changes were made as a result of the Pre-DP review, markup showing these changes shall be provided.
• For a Revision, a markup from the baseline draft should be included.
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.
• A Comment Resolution Record is required. This should be the electronic comment resolution records kept on the SMPTE web site. In some situations the Project Group may wish to keep other records. See the Standards Operations Manual for guidance.

After a successful DP vote the Draft Publication Vote Package documents shall not be edited by the Project Group participants or the Technology Committee Chair(s) with the exception of changing the document status. If new editorial issues are found, these should be documented and given to SMPTE HQ (see section SMPTE HQ Editing Publication Document Package.)

ST Audit Document Package

This document package is the responsibility of the Technology Committee Chair(s) and shall contain:

• A clean version of the document marked as “DP.”
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.
• A Comment Resolution Record is required. This should be the electronic comment resolution records kept on the SMPTE web site. If the Project Group kept other records, these must be included. See the Standards Operations Manual for guidance.

SMPTE HQ Editing Publication Document Package

The Technology Committee Chair(s) shall provide a document package to SMPTE HQ that includes:

• A clean master copy.
• If the document has one or more Element(s), the Element(s) or instructions for acquiring the Element(s) shall be included.
• Any original artwork, figures, drawings or similar material that will be needed to prepare the document and its elements for publication and long-term maintenance. These documents shall be in the formats described in section Publication Formats and Elements of this Administrative Guideline.
• A document with notes about any editorial issues discovered after the Draft Publication Vote documents are distributed may be included.

After each document achieves a successful ST Audit, SMPTE staff will prepare it for publication. The Technology Committee Chairs(s), Project Group Chairs(s) and Document Editor(s) who are responsible for the document are expected to review and approve it before publication.