Writing Technical Frameworks and Supplements

Guidance for Authors and Editors

This page is intended to provide basic information and links to resources to be used in developing IHE technical framework documents including supplements and final text volumes for publication.

Document Templates

IHE technical documents are based on standard templates, which have been developed to maintain consistency across documents and domains. The template for creating a new profile supplement is available from the IHE ftp site: ftp://ftp.ihe.net/Document_templates/Supplement_template/. The current version (for the 2010 development cycle) is 7.4.

The supplement template includes standard document sections to guide profile development. There is some variation in the use of standard sections across domains and in profiles with differences in purpose and scope. The Patient Care Coordination domain, for example, has developed a variation on this template to accommodate profiles focused on the content of structured documents. Authors should consult their Technical Committee co-chairs about recommended practice in their domain.

It is possible that we may in future incorporate new elements introduced by PCC and others into the common template. The Domain Coordination Committee is responsible for making decisions about the form and consistency of documentation. Comments about the supplement template can be directed to that committee via secretary@ihe.net.

Editing in MS-Word

MS Word is the tool used to develop IHE technical documents. Versions of MS-Word differ significantly. Tutorial with screenshots for the most common current versions of Word are linked below.

• Word 2007

They describe the following regular tasks in authoring or editing a document based on the supplement template:

1) Starting a New Document. When starting a new supplement document, use the latest version of the supplement template, available on the ftp site at ftp://ftp.ihe.net/Document_templates/Supplement_template/. (Sticklers will note that the supplement template is actually an MS-Word document {.doc} and not an MS-Word template {.dot}. We don't need to worry over the implications here.) This will contain the most current boilerplate text (mainly in the Foreword section) and the generally approved set of sections to be edited.

The template includes strings of <red text in angle brackets> that are to be replaced with information specific to the profile (eg, titles, domain and author names, dates). Once these sections are filled in, the angle brackets should be removed and the new text should be turned into standard (black) font styles.

2) Using MS-Word Styles. To maintain the consistency of IHE documents, please use the styles defined in the supplement template to format text in the document. The template should contain all of the styles required for standard elements. In either common version of Word, you can open the Styles palette and (mostly) restrict the available styles to those recommended in the template. You access the palette differently in the two versions. With the palette open, you can select any block of text in the document and apply the appropriate style to it.

The Styles are selectable in a window on the Word toolbar. To open a toolbar containing these styles go to Format and select Styles and Formatting. A toolbar appear on the right showing all formatting used in the document. From the dropdown at the bottom of the toolbar, select Available Styles. Select text in the document and click on a style from this list to apply the selected style to the selected text.

3) Cutting and Pasting from Other Documents. Importing styles from other Word documents can harm the appearance and functioning of the document you are producing. Imported styles are a little like invasive species: it takes some vigilance to keep them out and they are even harder to get rid of once they get in. Unfortunately, the default behavior of MS-Word when performing a simple cut-and-paste from document to document is to maintain the style associated with the pasted text in its source document and import that style into the style palette of the destination document. So if you need to import from another document, please follow these steps:

a. Copy the text from the source document

b. Place your cursor where the selection is to be added

c. Select Edit (or Paste):Paste Special: Unformatted Text

This will import the text and apply the style in use at the point of its insertion in your document. You can the apply to it any additional formatting needed using the Style palette as described above.

4) Adding or Editing Figures: To create stable diagrams in the TF document, editors must use the following method:

a. Place cursor in the text where the diagram is to be inserted; the cursor should be on a blank line with only a paragraph tag.

b. Select "Insert: Object: Microsoft Word Picture"

For efficiency and consistency it is generally best to base new diagrams on existing ones (e.g., Use Cases, Transaction Diagrams, etc.). After creating the new diagram (as described above), find a similar diagram from which to draw content. Double click on the source diagram to open it, copy all the desired pieces to the clipboard (using Shift+mouseclick to select). Open the new diagram, paste in the borrowed pieces and edit as desired. Redraw the diagram boundaries as necessary and close the picture.

The Structure of Technical Frameworks

An IHE Technical Framework is a collection of documents that define the specification and underlying implementation details of IHE Profiles that have been made Final Text.

Each IHE Domain is responsible for the development and maintenance of its Technical Framework.

<How you should structure your Tech Framework>

Volumes

Each Technical Framework is published in several volumes.

• Volume 1 is titled "Profiles".
  • It defines the Profile, the use cases, the actors involved and the requirements for conformance.
• Volume 2 is titled "Transactions", "Content", or "Transactions and Content".
  • It defines the Transactions and Content used by the Profiles.
  • Some domains subdivide Volume 2 into multiple documents when it becomes too large for editing.
• Volume ? is titled "National Extensions"
  • It defines approved regional variations

Section Numbering

Each profile in Volume 1 should have its own level 1 section (e.g. 4. Echocardiography Workflow)

When a profile is retired/deprecated, the next version of the framework is published with the contents of that section removed and replaced by a statement that the profile has been retired/deprecated.

• this keeps chapter numbers stable so as not to disrupt cross references
• this also provides a clear disposition of the profile for people who come searching for it

Supplemental information which does not seem to belong in a Profile section should be placed in an Appendix at the end of the volume. This avoids non-Profile sections from getting interspersed when new sections are added for new profiles.

Each transaction or content definition in Volume 2 should have its own level 2 section (e.g. 3.17 Retrieve Document)

When a transaction or content definition is retired/deprecated, the next version of the framework with the contents of that section removed and replaced by a statement that the transaction/content definition has been retired/deprecated.

• this keeps section numbers stable so as not to disrupt cross references
• this also provides a clear disposition of the profile for people who come searching for it

When Volume 2 is split into multiple documents (e.g. for logistical or marketing reasons), each should have the same Level 1 sections, but the Level 2 section numbering in the new document should pick up where the numbering in the previous document left off. E.g. the last transaction in Volume 2a, might be in section 3.23, and the first transaction in Volume 2b would be in section 3.24.

• this keeps section numbers corresponding to the transaction # which makes it easier to find material and create correct cross-references.

The stability of cross-references is important since it is not uncommon for profiles and transactions to be referenced by other domains in separate Technical Frameworks making it a challenge to identify and fix broken references.

Note that the first two Level 1 sections in both Volume 1 and 2 are either standard boilerplate material, or follow a standard format which new domains are encouraged to follow as well.

Appendices

<Explain guidelines for what to move to appendices>

<Topics that should be addressed in a TF>

<Boilerplate material>

Supplements

A Supplement is a document that specifies a new profile (both with Volume 1 and subsequent Volume material), or an extension to an existing final text Profile.

Supplements may be of Public Comment or Trail Implementation status.

Supplements are drafted using the current approved supplement template.

Revision Number

The initial Public Comment release of any supplement will be numbered Rev. 1.0. The subsequent trial implementation release of that supplement (if any) will be numbered Rev. 1.1. Any subsequent revisions of the supplement will be incremented one digit for each additional cycle of revision. Thus, a second, revised public comment version will be numbered Rev. 2.0; a second trial implementation version will be numbered Rev. 2.1, etc.

Editing Conventions

TF References

To reference material elsewhere in this or another IHE Technical Framework or Supplement:

• IHE XXX TF-n to refer to a Technical Framework volume
• IHE XXX TF-n:3.5.9.1 to refer to a specific Technical Framework section
• IHE XXX Sup-YYY to refer to a Supplement

XXX = the "acronym" for the IHE Domain

n = the volume number

YYY = the "acronym" for the Supplement

<need to settle on a notation for editions/revisions/dates of volumes and/or supplements>

• IHE RAD Sup-REM-PC
• IHE RAD 2008 TF-1

<What is the version intended to reflect? Annual Edition? CPs? Re-publication?>

Editing Tools

<Tips and Conventions for using different tools to edit/author/review Tech Frameworks/Supplements>