Difference between revisions of "Writing Technical Frameworks and Supplements"

Revision as of 14:19, 19 March 2014

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 at ftp://ftp.ihe.net/DocumentPublication/CurrentPublished/DocumentTemplates/Technical_Framework_Supplement_Template/. As of 2013-05-13, the current version is Version 10.3.

A white paper template is available at ftp://ftp.ihe.net/DocumentPublication/CurrentPublished/DocumentTemplates/White_Paper_Template/

Templates for the Technical Framework Volumes are currently in development and when ready, will be available at ftp://ftp.ihe.net/DocumentPublication/CurrentPublished/DocumentTemplates/Technical_Framework_Volume_Templates/

The supplement template includes standard document sections to guide profile development. This supplement template is for use by ALL domains. Beginning with Version 8.0, the template includes updates to accommodate profiles focused on the content of structured documents. Authors should consult their Technical Committee co-chairs about recommended practice in their domain.

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.

Matters of scheduling, committee timelines, methods of collaboration, sharing and publication of draft materials and the like are also outside the scope of these guidelines. Questions on such matters should be referred to the Co-chairs and secretariat of the relevant committee.

A video tutorial, recorded from a Webinar and covering the material below, is available at http://www.ihe.net/flash/TechnicalCommitteeAuthorsTcon-2010012814/index.html

Editing in MS-Word

IMPORTANT NOTE TO AUTHORS: When editing an already published document (e.g., going from PC to TI or updating a TI version), please obtain the most recent published version from the Current Published ftp Directory, not the ftp site of a specific domain. If this is not done, it is likely edits will be made to an outdated version and you will need to redo your work.

MS Word is the tool used to develop IHE technical documents. While versions of MS-Word differ significantly, this tutorial describes the general procedures for 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/DocumentPublication/CurrentPublished/DocumentTemplates/Technical_Framework_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, title, 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. The Foreword contains additional instructions for authors, editors and readers. Review it and discuss with your committee co-chairs if you have questions.

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 Word you can open the Styles palette by selecting "Format: Styles and Formatting" in older versions of Word and by clicking the small arrow at lower right of the Styles toolbar in the Home tab in Word 2007. With the palette open, you can select any block of text in the document and apply the appropriate style (by clicking on it in the palette). Select the Option to show "Available Formatting" in older versions and styles "In current document" in Word 2007. The supplement template contains styles for nine levels of headers, body text, numbered and bulleted lists, insert and delete text markings, instructions for the editor, table entries, table headers and table titles, figure titles, xml examples and more.

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. To avoid this, you need to take one of two approaches.

You can remove source styles and formatting before pasting copied text by taking the following steps:

a. Copy the text from the source document

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

c. Select Edit (or, in MS-W 2007, 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 then apply to it any additional formatting needed using the Style palette as described above.

You can also remove source styles after the copied text is pasted in. Click on the small clipboard icon that appears at the base of the inserted text. Select "Match Destination Formatting". The inserted text assumes the style in use at the point of insertion and no new styles are imported into the document.

4) Adding or Editing Tables. Frequently tables are imported into supplements from other documents (other supplements or base standards documents). Tables carry their own formatting and styles. Frequently they also have somewhat intricate structures: merged cells, multi-column rows, etc. You can copy tables and preserve their structures without importing source styles by using the clipboard icon and selecting "Match Destination Formatting" as just described.

The supplement template provides styles for Table Entry and Table Entry Header. The standard IHE style is to shade header row background at 15% gray. For tables that go across multiple pages, you should place your cursor in the header row, right click and select "Table Properties" open the "Row" tab and click "Repeat as header row at the top of each page".

The table title goes above the table and should have the Table Title style applied to it. Tables are numbered sequentially within a section; the table number is thus the full section number, followed by a hyphen, followed by the cardinal number of the table within the section, followed by a colon and then the table name (e.g., Table 3.2.3.1.4-1: Actor Options).

5) Adding or Editing Figures. The supplement template contains simple sample Actor, Process Flow, Use Case Role and Interaction diagrams. These can be edited and duplicated as needed. To edit, double-click the figure to open it in the Word drawing tool. You can then select, copy, edit, remove, resize, duplicate and rearrange the elements of the figure or add new ones to meet your needs. When finished close the drawing tool, which appears as a separate window in Word, by clicking the X at upper right.

Note that Windows 2007 introduced a new method for inserting drawings into Word documents. Under the Insert tab, select the down arrow under Shapes and select New Drawing Canvas at the bottom of the drop down box. This will create a drawing canvas onto which you can place shapes, lines, arrows, text boxes, etc, including ones copied from other Word drawings. Note that in copying elements from older Word drawings you can use the Select Tool in the Editing box of the Home tab to select objects and Control-c to copy. Once the elements you want are copied to the clipboard you can paste them into your new canvas and use the new and improved tools to edit them further as needed. The new canvas needs to be drawn large enough to accommodate all the elements you are pasting in.

Some supplements have used diagrams significantly different from the samples included in the template. The degree of allowable divergence is, again, a matter for discussion within committees and in the Domain Coordination Committee. In devising new diagrams avoid introducing formats that cannot be edited natively in Word since they will likely need to be edited later by someone who may not have the same tools available as the author. Word allows insertion of objects created in Visio and PowerPoint, as well as graphics files and PDFs. In some instances introducing such objects has compromised the stability of documents. Again, anything that cannot be edited by collaborators is not really appropriate.

To make a request to add a non-standard format diagram, the request/approval form must be filled out and the source file must be provided.

Non-standard Diagram Request Form

Non-standard Diagram Request Process

Figure title numbering follows the same convention as table numbering. The figure title (which has its own style) goes at the base of the figure.

6) Updating Tables of Contents. After you have completed editing a supplement draft and are ready to prepare it for distribution or publication, you should update the table of contents. Click on the table of contents to select, then right click and select "Update Field: Update entire table". This should add any new section headings (to level 3) inserted into the document, as well as updating all section page numbers.

7) Importing Template Styles into an Existing Document. Occasionally you may want to import styles from the supplement template into an existing document, for example to repair a style that has become corrupted. (This frequently happens to styles--especially Headers and Body text--after multiple style variations have been applied to them.) You can do so by keeping a copy of the unedited template document locally. In the document you are editing, you can use Word's Style Organizer to import styles from the template.

In Word 2007 you access the Organizer from the Styles palette by clicking the "Manage Styles" icon (the one featuring the little pencil) at the base of the palette window and clicking the Import/Export button. In older versions the Organizer is under "Tools: Templates and Add-ins".

The Organizer has two windows. The styles in your current document will appear on the left. By default, the right window will show the styles in the normal.dot Word template. Click "Close File" under the right window and then "Open File". You can navigate to the supplement template (you will need to set Word to look for "All Word Documents") and select it. The right window in Organizer will now feature the styles available in the supplement template, which you can import into the document you are editing. If you overwrite a style you are using in that document, the basic style you import will be applied to the overwritten style and will remove any font-level formatting you might have applied to the overwritten style.

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

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 trial implementation version will be numbered Rev. 1.2; a second public comment version will be numbered Rev. 2.0, 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?>

@@ Line 133: / Line 133: @@
 ===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.
+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 trial implementation version will be numbered Rev. 1.2; a second public comment version will be numbered Rev. 2.0, etc.
 ==Editing Conventions==