V3 PubProcess - Prepare Freehand MIF

02.00...Manual Preparation of Freehand MIF Files

Several V3 files, usually those in the Infrastructure and Help sections, are hand-edited MIF files. These "freehand" documents are validated using the mif-model-package.xsd schema. The instructions below provide an overview of the files and guidance for editors of the files. In addition, these instructions provide several examples of common document structures, such as block items – like lists and tables – inline items – like font styles and anchors – and other elements – such as embedded images or references to other V3 objects and specifications.

02.01...Template Files for Freehand MIF Files

A complete document is constructed from three MIF files (where "filename" is the V3 Publishing named identifier for the document set):

• [filename]-publication.mif – The "parent" document. This is a short file whose purpose is to define the high-level publication information. Most likely you will not need to do any editing of this file beyond periodically updating the date in the renderingInformation element.
• [filename]-ballot.mif – This file contains information specific to the CURRENT BALLOT status of the document. Important sections in this file include the Co-Chairs, Contributors and Editors List, the Notes to Readers, the Summary of Changes from Previous Release, and related sections such as open issues, scope of ballot, etc.
• [filename]-package.mif – This file contains the ACTUAL TEXTUAL CONTENTS of the document. The construction of this document should look familiar to those who have edited other V3 XML files in the past.

02.02...Common References for Freehand MIF Files

The publication, ballot and package MIF files contain several common elements and references. In general, editors should not need to make many updates to these elements and references and special care should be taken when making changes.

The items in this file that CAN be updated are as follows:

• The application attribute in mif:renderingInformation SHOULD be set to "manual" although this is recommended but not mandatory.
• The renderingTime attribute in mif:renderingInformation SHOULD be periodically updated to the current date, although hours and minutes should be considered inconsequential.
• The title attribute in both the mif:package and mif:freehandDocument elements SHOULD be the same and should match the official name of the document. This is the descriptive name for the package in circumstances where the 'name' (as in mif:packageLocation) is more of an identifier.

In general, the following items SHOULD NOT be changed:

• The name attribute in mif:packageLocation should be the same in all three files. This name MUST correspond to the V3 Publishing defined name for the document set. This is a controlled name and must be insured to be unique and registered in the HQ publishing system in order for the document to properly published. The various documents will be provided from HQ with these values set.
• The schemaVersion attribute in mif:package MUST be "2.2.0".
• The xsd path string in the xsi:schemaLocation attribute in mif:package MUST point to the location of the mif-model-package.xsd in order for this document to validate. This string will be preset to "../../../ToolFiles/MIF2_2Schemas/mif-model-package.xsd". (Experienced editors MAY modify the path to mif-model-package.xsd in instances where their local directory structure does not to correspond to this path; for instance, an editor might place the schema file in the same directory as the document being edited and shorten to the path string to just "mif-model-package.xsd".)

02.03...Document-Specific References for Freehand MIF Files

The publication, ballot and package MIF files each serve a specific function and will have elements and references not shared by the other files. This section provides an overview of some of these key elements and references for each specific file.

[FileName]-publication.mif (The parent file for the document set):

• Other than periodically updating the renderingTime attribute of the renderingInformation element, you should not need to make any changes to this file.

[FileName]-ballot.mif (The file containing the ballot-specific information for the document set):

• The renderingTime attribute of the renderingInformation element SHOULD be periodically updated to reflect the current date. Only the date should be updated; the minutes and sections SHALL be considered inconsequential.
• The groupName attribute of the responsibleGroup element SHOULD reflect the name of the WG responsible for balloting the document set. Only a single WG should be listed here; in cases where more than one WG are sponsoring a ballot, the WG of record with the HL7 PMO SHALL be listed.
• The email element under the responsibleGroup element SHOULD be used to provide a primary contact email for the WG. (Note that the email address shall take this form: "<email>mailto://name@organization.org</email>)

02.04...Ballot-Specific Information – [FileName]-ballot.mif

The ballot MIF file contains information specific to the balloting of the information.

• Co-Chairs, Contributors and Editors List – This div section identifies individuals who contibuted to the creation or maintenance of the package. The Contributors list SHOULD contain a listing of the following individuals:

1 - WG Co-Chairs

2 - MnM Facilitator

3 - Vocabulary Facilitator

4 - Publishing Facilitator

Other individuals SHALL be acknowledged in the Acknowledgements section of the Preface.

• Notes to Readers (REQUIRED) – This section SHOULD include the ballot level and version specific to the document release. It SHOULD also contain any other information relevant to readers of the material, such as ballot scope.
• Acknowledgements – This section SHOULD be used to formally acknowledge individuals and organizations that contributed to the creation of the document that are not listed in the Contributors section.
• Changes from Previous Release (REQUIRED) – This section SHALL list all Substantive Changes since the last ballot of the material.
• Prerequisites, Assumptions and Conventions – This section SHOULD be used to provide the reader with an overview of important assumption, any prerequisites needed, and an overview of background material useful to understanding the document.
• Known Issues or Planned Changes – This section SHOULD be used to provide the reader with a brief overview of areas that the WG has identified as requiring additional work and give some indication as to what will be done to address these issues.
• Other Notes – This section SHOULD be used to provide the reader with any additional information the WG feels will be helpful in reviewing the document.

Note that all of these sections are contained within divs. Div setup is as follows:

• hl7Id Attribute – Takes the form hl7Id="prefNotes" where the hl7Id is constructed using a simple mnemonic identifying the general section of the document (such as pref, for Preface) and specific section (such as Changes, for Changes from Last Ballot).
• title Attribute – title="Notes to Readers" where the title contains text to clearly and uniquely identify the specific section of the document.