Writing Technical Frameworks and Supplements

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

Chapters & Sections

Each profile in Volume 1 should have its own chapter.

<<Proposed for approval by Cochairs>>

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

• 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 chapter should be placed in an Appendix at the end of the volume. This avoids non-Profile chapters from getting in the way of adding chapters for new profiles.

Each transaction or content definition in Volume 2 should have its own level 2 section (e.g. 3.4

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.

• 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 Chapters, but the 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 chapters 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>

Editing in MS-Word

1) When starting a new TF document, begin by using either an existing TF document or the ihe.dot template (available on the ftp site at ftp://ftp.ihe.net/Document_templates/) as a basis.

2) To maintain the stability and integrity of the Technical Framework (TF) documents and their template, it is imperative that all editors avoid importing formatted text from other documents. Unfortunately, this is the default behavior of MS-Word when performing a simple cut-and-paste from document to document. Thus, an editor importing text into the TF from any other document must perform the following steps:

a. Cut or copy from the source document

b. Place cursor where the selection is to be added

c. Select "Edit:Paste Special: Unformatted Text"

3) To maintain the consistency of the TF, apply only the Styles defined in the template to text in the document. 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.

4) 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.

IHE Wiki

<Keith would be the best one to write this section>