Difference between revisions of "Writing Technical Frameworks and Supplements"
(→Editing in MS-Word: changed links and refs from ftp to Google Drive) |
|||
(44 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
+ | == '''IMPORTANT NOTE TO AUTHORS/EDITORS:''' == | ||
+ | |||
+ | 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 [https://drive.google.com/drive/folders/1qJVFWjhzb_5JgxSDGGE8j-l4FpERyhsG Current Published Google Drive folder], '''not''' the Google Drive folder of a specific domain or a copy you may have locally on your computer. If this is not done, it is likely edits will be made to an outdated version and you will need to redo your work. | ||
+ | |||
==Guidance for Authors and Editors== | ==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. | 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=== | ===Document Templates=== | ||
− | IHE technical documents are based on standard | + | IHE technical documents are based on standard '''[[Official Templates]]''', which have been developed to maintain consistency across documents and domains. |
+ | |||
− | 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 | + | 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 | + | The [[Domain Coordination Committee]] is responsible for making decisions about the form and consistency of documentation. |
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. | 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 http://www.ihe.net/flash/TechnicalCommitteeAuthorsTcon-2010012814/index.html] | :::* A video tutorial, recorded from a Webinar and covering the material below, is available at [http://www.ihe.net/flash/TechnicalCommitteeAuthorsTcon-2010012814/index.html http://www.ihe.net/flash/TechnicalCommitteeAuthorsTcon-2010012814/index.html] | ||
+ | |||
+ | ===IHE Document Publication Google Drive Folder - Instructions for Use=== | ||
+ | The [[IHE Document Publication Google Drive Folder Structure]] page contains links to the IHE Google Drive folder used as the repository for IHE Technical Framework publications. For ease of navigation, it also contains an overview of the Google Drive folder structure. | ||
+ | |||
+ | '''The Google Drive Folder is where authors can obtain the most recent Word versions of current published IHE Technical Framework, Volumes, Supplements and White Papers that need updating.''' | ||
+ | |||
+ | ==Gaining Approval for New or Modified Actors Transactions and Glossary Terms (Required Process)== | ||
+ | Beginning November 2019, an approval process for new or modified actors, transactions and glossary terms was implemented. See the [https://wiki.ihe.net/index.php/Approval_Process_for_IHE_Actors,_Transactions_and_Glossary_Terms Approval Process for Actors, Transactions and Glossary Terms] wiki page for instructions on this new process. | ||
+ | |||
+ | |||
+ | ==Editing Conventions== | ||
===Editing in MS-Word=== | ===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 [ | + | '''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 [https://drive.google.com/drive/folders/1qJVFWjhzb_5JgxSDGGE8j-l4FpERyhsG Current Published Google Drive folder], '''not''' the Google Drive folder 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. |
Line 20: | Line 36: | ||
− | '''1) Starting a New Document.''' When starting a new supplement document, use the latest version of the supplement template, available on the | + | '''1) Starting a New Document.''' When starting a new supplement document, use the latest version of the supplement template, available on the IHE Google Drive folder at [https://drive.google.com/drive/folders/13nsG6u3V--lQgCXCZlt0M73-oRgSXE9q https://drive.google.com/drive/folders/13nsG6u3V--lQgCXCZlt0M73-oRgSXE9q]. (Sticklers will note that the supplement template is actually an MS-Word document {.docx} and not an MS-Word template {.dotx}. 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 < | + | The template includes strings of <text in angle brackets> that are to be replaced with information specific to the profile (e.g., title, domain names, dates). Once these sections are filled in, the angle brackets should be removed. 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 | + | '''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 clicking the small arrow at the lower right of the Styles toolbar in the Home tab (or by selecting "Format: Styles and Formatting" in older versions of Word). 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 "All Styles". 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. |
Line 33: | Line 49: | ||
::a. Copy the text from the source document | ::a. Copy the text from the source document | ||
::b. Place your cursor where the selection is to be added | ::b. Place your cursor where the selection is to be added | ||
− | ::c. Select Edit (or, in MS-W 2007, Paste): Paste Special: Unformatted Text | + | ::c. Select Edit (or, in MS-W 2007 and later, 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. | 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. | ||
Line 41: | Line 57: | ||
'''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. | '''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 | + | The supplement template provides styles for Table Title,Table Entry Header and Table Entry. 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 section number, followed by a | + | 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. | + | '''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. | 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 | + | 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. | 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. | ||
Line 65: | Line 81: | ||
'''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. | '''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". | + | In Word 2007 and later, 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 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. | ||
+ | |||
+ | ===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 '''[[Domains|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?>'' | ||
+ | |||
==The Structure of [[Frameworks| Technical Frameworks]]== | ==The Structure of [[Frameworks| Technical Frameworks]]== | ||
Line 83: | Line 117: | ||
* Volume 1 is titled "Profiles". | * Volume 1 is titled "Profiles". | ||
− | ** It defines the Profile, the use cases, the actors involved and the requirements for conformance. | + | ** It defines the Profile, the use cases, the actors involved and the requirements for conformance. |
− | * Volume 2 is titled "Transactions | + | ** Some domains subdivide Volume 1 into multiple documents when it becomes too large for editing (e.g., 1a, 1b, etc.). |
− | ** It defines the Transactions | + | * Volume 2 is titled "Transactions". |
− | ** Some domains subdivide Volume 2 into multiple documents when it becomes too large for editing. | + | ** It defines the Transactions used by the Profiles. |
− | * Volume | + | ** Some domains subdivide Volume 2 into multiple documents when it becomes too large for editing (e.g., 2a, 2b, etc.). |
+ | *Volume 3 is titled "Content" | ||
+ | ** It defines the Content used by the Profiles | ||
+ | ** Prior to the existence of Technical Framework Volume templates, some domains combined Content with Transactions in Volume 2 (a revamp is underway to move content to Volume 3 for all domains) but this is not accepted practice moving forward | ||
+ | * Volume 4 is titled "National Extensions" | ||
** It defines approved regional variations | ** It defines approved regional variations | ||
===Section Numbering=== | ===Section Numbering=== | ||
− | Each profile in Volume 1 should have its own level 1 section (e.g. 4. Echocardiography Workflow) | + | 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. | 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. | ||
Line 98: | Line 136: | ||
:* this also provides a clear disposition of the profile for people who come searching for it | :* 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. | + | 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 | + | Each transaction in Volume 2 should have its own level 2 section (e.g., 3.17 Retrieve Document) |
− | When a transaction | + | When a transaction 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 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 | :* 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. | + | 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. For example, 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. | :* this keeps section numbers corresponding to the transaction # which makes it easier to find material and create correct cross-references. | ||
Line 115: | Line 153: | ||
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. | 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=== | + | ===General Introduction and Shared Appendices=== |
− | + | Information about the IHE General Introduction and Shared Appendices can be found [http://wiki.ihe.net/index.php/Official_Templates#General_Introduction_and_Shared_Appendices here]. | |
+ | ===Revision Number=== | ||
− | + | ====Technical Framework Supplements==== | |
+ | The revision of the initial public comment release of any supplement will be numbered in whole numbers. For example: | ||
+ | * 1.0 | ||
+ | * 2.0 | ||
− | + | The revision of the subsequent trial implementation release(s) of that supplement (if any) will be numbered in decimal numbers. For example: | |
+ | *1.1 | ||
+ | *2.1 | ||
+ | Any subsequent revisions of the supplement will be incremented one digit for each revision. See the table below for an example. | ||
− | ===Revision | + | {| style="width:50%" border="1" cellpadding="3" |
+ | ! Initial PC Revision | ||
+ | ! Subsequent TI Revision | ||
+ | ! Updated TI Revision | ||
+ | ! If the supplement goes back to PC | ||
+ | ! Subsequent TI revision | ||
+ | |- | ||
+ | | 1.0 | ||
+ | | 1.1 | ||
+ | | 1.2 | ||
+ | | 2.0 | ||
+ | | 2.1 | ||
+ | |} | ||
− | |||
− | == | + | ====Technical Frameworks==== |
+ | In most cases, Technical Frameworks are versioned in whole numbers. In some unique circumstances, a Technical Framework Volume may be versioned in decimal numbers (e.g., 2.1). For example, if Volume 1 is updated mid-cycle to | ||
+ | correct a typo that may cause confusion, that Volume is incremented in decimal numbers (e.g., Revision 2.0 to Revision 2.1). | ||
− | |||
− | + | ==See Also== | |
− | |||
− | |||
− | |||
− | + | ===[[Public Comment Process]] for details on collecting public comment on draft documents=== | |
− | |||
− | |||
− | + | ===[[Technical Framework Publication Process]] for details on how to submit Technical Framework documents for publication.=== | |
− | |||
− | |||
− | + | ===[[Cookbook_for_Security_Considerations]]=== | |
− | == | + | ===[[OID_Registration]]=== |
− | [[ | + | ===[[Guidance_on_writing_Profiles_of_FHIR]]=== |
− | [[ | + | ===[[Cross-Domain_Dependency_Process]]=== |
Latest revision as of 11:23, 23 June 2020
IMPORTANT NOTE TO AUTHORS/EDITORS:
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 Google Drive folder, not the Google Drive folder of a specific domain or a copy you may have locally on your computer. If this is not done, it is likely edits will be made to an outdated version and you will need to redo your work.
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 Official Templates, which have been developed to maintain consistency across documents and domains.
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.
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
IHE Document Publication Google Drive Folder - Instructions for Use
The IHE Document Publication Google Drive Folder Structure page contains links to the IHE Google Drive folder used as the repository for IHE Technical Framework publications. For ease of navigation, it also contains an overview of the Google Drive folder structure.
The Google Drive Folder is where authors can obtain the most recent Word versions of current published IHE Technical Framework, Volumes, Supplements and White Papers that need updating.
Gaining Approval for New or Modified Actors Transactions and Glossary Terms (Required Process)
Beginning November 2019, an approval process for new or modified actors, transactions and glossary terms was implemented. See the Approval Process for Actors, Transactions and Glossary Terms wiki page for instructions on this new process.
Editing Conventions
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 Google Drive folder, not the Google Drive folder 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 IHE Google Drive folder at https://drive.google.com/drive/folders/13nsG6u3V--lQgCXCZlt0M73-oRgSXE9q. (Sticklers will note that the supplement template is actually an MS-Word document {.docx} and not an MS-Word template {.dotx}. 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 <text in angle brackets> that are to be replaced with information specific to the profile (e.g., title, domain names, dates). Once these sections are filled in, the angle brackets should be removed. 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 clicking the small arrow at the lower right of the Styles toolbar in the Home tab (or by selecting "Format: Styles and Formatting" in older versions of Word). 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 "All Styles". 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 and later, 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 Title,Table Entry Header and Table Entry. 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.
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 and later, 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.
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?>
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.
- Some domains subdivide Volume 1 into multiple documents when it becomes too large for editing (e.g., 1a, 1b, etc.).
- Volume 2 is titled "Transactions".
- It defines the Transactions used by the Profiles.
- Some domains subdivide Volume 2 into multiple documents when it becomes too large for editing (e.g., 2a, 2b, etc.).
- Volume 3 is titled "Content"
- It defines the Content used by the Profiles
- Prior to the existence of Technical Framework Volume templates, some domains combined Content with Transactions in Volume 2 (a revamp is underway to move content to Volume 3 for all domains) but this is not accepted practice moving forward
- 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 in Volume 2 should have its own level 2 section (e.g., 3.17 Retrieve Document)
When a transaction 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. For example, 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.
Information about the IHE General Introduction and Shared Appendices can be found here.
Revision Number
Technical Framework Supplements
The revision of the initial public comment release of any supplement will be numbered in whole numbers. For example:
- 1.0
- 2.0
The revision of the subsequent trial implementation release(s) of that supplement (if any) will be numbered in decimal numbers. For example:
- 1.1
- 2.1
Any subsequent revisions of the supplement will be incremented one digit for each revision. See the table below for an example.
Initial PC Revision | Subsequent TI Revision | Updated TI Revision | If the supplement goes back to PC | Subsequent TI revision |
---|---|---|---|---|
1.0 | 1.1 | 1.2 | 2.0 | 2.1 |
Technical Frameworks
In most cases, Technical Frameworks are versioned in whole numbers. In some unique circumstances, a Technical Framework Volume may be versioned in decimal numbers (e.g., 2.1). For example, if Volume 1 is updated mid-cycle to correct a typo that may cause confusion, that Volume is incremented in decimal numbers (e.g., Revision 2.0 to Revision 2.1).