ITI Editors Guidelines

To new editors

You have been assigned a document to write for the ITI domain: First of all congratulations and thank you for your help. It might seem frightening at first but we'll do our best to guide you through this experience as painlessly as possible.

These wiki pages will provide you with guidance and advice for editing your document. Should they not be enough, you can always ask experienced ITI members, specifically:

• your mentor (for profiles or white papers);
• the co-chairs of the ITI committee which will publish the document (most of the time it will be the technical committee);
• any other experienced ITI members.
  

We also encourage you to view the video tutorial provided by IHE that explains the constraints on use of MS Word to edit IHE documents. These constraints are important to maintain consistency across all IHE documents. Please see the end of section Document Templates.

ITI Production cycle

All documents produced by the ITI domain are developed within the ITI production cycle that begins in the early fall by the submission of profile and white paper proposals and ends by the publication of new profiles, new white papers and updated Technical Framework toward the end of the summer of the year after. The following diagram is showing the ITI production cycle in blue and in red the various documents produced by the ITI domain.

Roles

The following roles are the main people taking part in the writing process of documents within the ITI domain. Other people with responsibilities during the ITI cycle (for publication for instance) aren't listed below since editors most likely won't have direct interaction with them.

• Author or Editor
  

An author (sometimes called an Editor) is the person who is responsible for the writing of a document. There is only one author per document although there might be as many co-authors as needed (see co-author section). In cases where there are co-author(s) for a document, the author is responsible for the coordination of the writing of the document with the co-author(s). An author is the primary contact for the document's progress, status and scheduled discussion. The author should not be changed during the cycle (i.e. an author should commit to be author for the document for the whole cycle). In cases of unexpected, extended unavailibility of an author, an identified co-author may stand for the author; this should however be avoided as much as possible.

• Co-author

A co-author is a person who participates in the writing of a document. There may be as many co-authors as needed for a document. The writing of a document between the author and the co-author(s) is coordinated by the author.

• Editorial Team

An editorial team consists of people committed to review and provide comments on a document many times during its development. Members of the editorial team have committed to review versions the document as they are available, provide comments and attend all meetings (t-cons or face to face) where the document is the main purpose of the meeting. The minimal number of times the editorial team is expected to review the document is defined in the "position in the cycle and milestones" section for each kind of document. The Editorial team should not be confused with co-authors. Members of an editorial team are not expected to write any part of the document. Editorial teams are provided for documents with a fairly long editorial cycle (supplements, white papers, user handbooks, large CPs...), but are generally not provided for short cycle documents (proposals or regular CPs).

• Mentor

A mentor is in charge of providing guidance on the editing process to the author of a document. For example, the mentor provides guidance on how to organize the work, where to submit the various updates of the document, which material to provide for which meetings and many more issues that come up during the development cyle. Mentors are not required to provide guidance as to the content of documents. Mentors are only identified for new authors with little knowledge of ITI processes; authors having previously authored a document are expected to need less mentoring and know how to engage the right people in the committee to answer questions that come up. For procedural questions, the mentor is the primary and first contact of the author; co-chairs are a second point of contact when the mentor needs backup.

Document types

The following sections specify content and milesstones for each document type.

Proposal

https://drive.google.com/drive/folders/13pSEFTaiXSS2W63o7F2lxGzeuP0YEeWZ

Detailed Proposal

ftp://ftp.ihe.net/DocumentPublication/DocumentTemplates/Profile%20Proposal-Brief%20and%20Detailed/

New profile

Aim of the document
A new profile is written to respond to use cases from a system interoperability point of view. The main use cases that the profile has to address are identified during selection of work items for the cycle (from the planning face to face meeting to the final decision). The profile has to describe those use cases (and possibly relevant additional ones). From the use cases, the profile derives technical actors and transaction(s) between the actors to address the use cases need in an interoperable way.

Structure of the document
A new profile is presented in a document called supplement and with the eventual aim of being integrated in the ITI Technical Framework. That integration is done after one or more year as a Trial Implementation Supplement and is described at <need to create this section>. Thus the structure of the supplement follows the Technical Framework structure :

• a volume 1 section describing the use cases and the technical actors addressing the use cases;
• a volume 2 section describing the technical transaction(s) and content between the technical actors.

The profile also includes section(s) on Security Considerations in volume 1 and/or volume 2 depending on the issues to address.

Volume 1

Volume 1 presents use cases preferably in a clinical way when appropriate. The use cases describe the issue that the profile is aimed at solving. Each use case is generally described in two sections: one about how it is working now and another one about how it should be working (i.e. what the profile will try to achieve). In order to keep the document within a manageable number of pages, it is suggested to limit the number of use cases presented in the supplement to a maximum of 3 (the most relevant ones). Any additional use cases needed for the development of the profile may be presented on the wiki (see "wiki and ftp updates" section below).

Volume 1 is also presenting the technical actors involved in the profile and their interactions through transaction(s) (the transactions themselves being detailed in volume 2).

Volume 2

Volume 2 is detailing each transaction on the technical level, explaining which standards are used and if necessary detailing the messages exchanged and the constraints put on the actors and transactions. Volume 2 also has a section for detailing the content of the exchanges between actors, if needed. Most of the time, content is not within ITI domain scope and an editor should ask for a technical committee decision before starting any work on content.

Security Considerations

Security Considerations are included in Volume 1 and/or Volume 2 after a risk analysis on the profile scope. Guidance for writing the Security Considerations are provided in the Cookbook for Security Considerations

Template
The IHE template directory holds the latest version of the Supplement Template to use for writing a profile

Position in the cycle and milestones
Work on a new profile starts as soon as the final decision on work items for the cycle is taken. The various steps in the writting of a new profile in relation to the various meeting of the ITI production cycle are described below as a guidance for editors:

Between the final decision on work items for the cycle and the winter technical face to face meeting

This period is devoted to the writing of the volume 1 section of the profile and a broad assessment of the standards for the volume 2 section. By the winter technical face to face, a draft should be ready for review by the committee. The draft should use the appropriate template and include:

• The use cases fully written for review during the winter technical face to face meeting
• The rest of volume 1 (list of actors and transactions) written with possible open issues clearly listed
• A list of possible standards that can be used for the profile with strengths and weaknesses of each if a choice must be made among them.

At least one tele-conference (referred to within the committee as "T-con" or "call") on the profile is planned by the technical co-chairs between the final decision and the winter technical face to face meeting. If one call is not enough, the editor can ask the co-chairs to plan additional calls.

At least one review of the material for the winter technical face to face meeting should be done prior to the face to face by the editorial team (and any other interested committee member). Editors have to plan this review so as to have the comments fully integrated in the draft before the face to face meeting (a period of one week is generally given for reviewing a document and providing comments but the editors and editorial team may agree on a different length during the calls).

Between the winter technical face to face meeting and the spring technical face to face meeting

This period is devoted to the integration of comments from the winter face to face in the volume 1 section and to the writing of the volume 2 section. By the spring technical face to face, a draft should be ready for review by the committee. The draft should include:

• The final volume 1 section
• The volume 2 section fully written (each transaction described, Security Considerations written) with possible open issues clearly listed

At least two T-cons on the profile is planned by the technical co-chairs between the winter and the spring face to face. If two calls are not enough, the editor can ask the co-chairs to plan further calls.

At least two reviews of the material for the spring technical face to face meeting should be done prior to the face to face by the editorial team (and any other interested committee member). Editors have to plan those reviews so as to have the comments fully integrated in the draft before the face to face meeting (a period of one week is generally given for reviewing a document and providing comments but the editors and editorial team may agree on a different length during the calls).

Between the spring technical face to face and the publication for public comments

This period is devoted to the integration of comments from the spring face to face in order to have the document ready for publication for public comments. By the date set during the face to face, the document should be completed with possible open issues that during the face to face the committee agreed on submitting for public comments.

There should be no need to organize a call between the spring face to face and the publication for public comments. Any issue with the document should be settled during the spring face to face meeting. In special cases a call may be used to review extensive changes recommended during the face to face meeting.

Between the publication for public comments and the end of the public comments period

There isn't much to do until the public comments period ends. It is however recommended to get a little ahead by regularly going to the IHE forum to review the comments as they arrive.

Between the end of the public comments period and the summer technical face to face meeting

This period is devoted to organize and process the comments received and update the document accordingly. A spreadsheet including all the comments received should be created by the editor. Each comment in the spreasheet should be either:

• resolved and the document should be updated accordingly;
• not resolved and the issue will be presented to the committee during the summer face to face by priority.

At least one review of the spreadsheet, of the resolution of comments and of the priorization of the unresolved comments should be done by the editorial team prior to the summer face to face (probably through e-mail but possibly during a call if the author and the editorial team manage to find a slot). The aim is to resolve as many of the comments as possible and to analyze the unresolved comments to present to the committee during the summer face to face for decision (if at all possible, the unresolved comments should be presented as a decision between alternatives with advantages and drawbacks outlined for each alternative). The comments will be treated by the order of priority defined by the editor. The priority should be defined to present the more difficult and/or impactfull comments first.

Between the summer technical face to face meeting and the final publication of the profile

This period is devoted to the integration of comments resolution from the summer face to face in order to have the document ready for final publication. By the date set during the face to face, the document should be completed and ready for final publication.

There should be no need to organize a call between the summer face to face and the final publication. Any issue with the public comments should be settled during the summer face to face meeting. In special cases a call may be used to review extensive changes recommended during the face to face meeting.

Support

Mentor

Each first time editor will be provided with a mentor. A mentor is a technical committee member experienced in writing a profile. The mentor will help the editor with any issue about the process of writing a profile. Any questions on issues like process, template, how to handle a call or any other question not connected to the content of the profile should be directed to the mentor who will do his/her best to provide an answer.

Editorial Team

For each profile, an editorial team will be defined during the fall technical face to face meeting. An editorial team is a group of technical committee members interested in the profile. Each member of an editorial team is committed to review the draft profile as needed (at least as often as presented in the "Position in the cycle and milestones" section) and provide the editor with input concerning the content of the profile.

Guidance on tools usage

Guidance on tools usage like how to upload documents on the ftp or update the wiki can be found there. Please read the ftp guidelines and the wiki guidelines before using those tools.

Also be aware that including "space" characters in the name of files uploaded on the ftp may lead to issues for downloading the files. "Spaces" characters (i.e. " ") in file names should be replace by the "underscore" character (i.e. "_" ).

wiki and FTP updates

FTP

The FTP is used to provide varous materials for review or publication:

• Drafts and Additional material: In the ITI section of the FTP, under the current year, there is a Technical_Cmte folder in which there is a Profile_Work folder including a folder for each profile. Each draft and additional material should be uploaded there during the year. The profile author is encouraged to organize subfolders below the profile folder as they wish. All shared material related to the profile should be placed within the profile folder, including presentations, background documents, working drafts and security risk spreadsheets.
• Public comments version: In the ITI section of the FTP, under the current year, there is a Technical_Cmte folder in which there is a PublicCommentSupplements folder. The version for public comments publication should be uploaded there.
• Final version: In the ITI section of the FTP, under the current year, there is a Technical_Cmte folder in which there is a TrialImplementationSupplements folder. The version for final publication should be uploaded there.
• Support materiel: In the ITI support material section of the FTP, there are folders for various support material. When the profile is released as Trial Implementation and the profile would benefit from support material for implementors, the support materials should be uploaded there. Prior to release as Trial Implementation support materials should be saved in the profile folder described above.

• examples are examples of code that can be used for developping a profile.
• schemas are defining the structure of the content of transactions for a profile.
• WSDL are the description of the web services used for a profile.
• packages are zip files including all support materials (examples, schemas, WSDLs) for a profile.

wiki

A specific page for each profile is created in the wiki. This page is for the editor to use. It can for instance be used to describe issues with the profile, to detail additional use cases that won't be included into the profile, for cooperative work on the support material...

New White Paper

Aim of the document
There are a variety of reasons why a new white paper is written. A new white paper can, for instance, explain an issue usually faced by IHE implementor and/or end user, explore a new technical orientation to see how it can be used later on in the ITI domain, analyze how technology may answer broad use cases (too broad for a profile) and later on lead to a profile. The topic of the white paper and its scope are identified during selection of work items for the cycle (from the planning face to face meeting to the final decision).

Structure of the document
As white papers may address a variety of topics, the structure of a new white paper is not set and must be defined for each new white paper based on the detailed scope defined during the planning face to face meeting and the first technical face to face meeting.

Template
The IHE template directory holds the latest version of the white paper template.The white paper template strucuture is a starting point and can be modified based on the specific needs of your white paper.

Position in the cycle and milestones
Work on a new white paper starts as soon as the final decision on work items for the cycle is taken. The various steps in the writting of a new white paper in relation to the various meeting of the ITI production cycle are described below as a guidance for editors:

Between the final decion on work items for the cycle and the winter technical face to face meeting

This period is devoted to define the outline of the white paper according to the scope and to identify the main issues that will need in-depth analysis before the writting of the corresponding section in the white paper. By the winter technical face to face, a detailed outline should be ready for review by the committee. The outline should use the appropriate template and include:

• The name of each section of the detailed outline for review during the winter technical face to face meeting.
• A one sentence description of the content of each section and if relevant description of issues to be discussed before the writing of the section (if possible each issue should be presented as a decision between alternatives with advantages and drawbacks outlined for each alternative).
• If possible fully written text for the section without any issue.

At least one tele-conference (referred to within the committee as "T-con" or "call") on the white paper is planned by the technical co-chairs between the final decision and the winter technical face to face meeting. If one call is not enough, the editor can ask the co-chairs at the end of the call to plan further call(s).

At least one review of the material for the winter technical face to face meeting should be done prior to the face to face by the editorial team (and any other interested committee member). Editors have to plan this review so as to have the comments fully integrated in the outline before the face to face meeting (a period of one week is generally given for reviewing a document and providing comments but the editors and editorial team may agree on a different length during the calls).

Between the winter technical face to face meeting and the spring technical face to face meeting

This period is devoted to the integration of comments from the winter face to face and to the writing of the white paper. By the spring technical face to face, a draft should be ready for review by the committee. The draft should be a fully written white paper with possible some remaining open issues to be resolved during the spring face to face meeting. Each open issue should, if possible, presented as a decision between alternatives with advantages and drawbacks outlined for each alternative).

At least two T-cons on the white paper is planned by the technical co-chairs between the winter and the spring face to face. If two calls are not enough, the editor can ask the co-chairs at the end of the call to plan further call(s).

At least two reviews of the material for the spring technical face to face meeting should be done prior to the face to face by the editorial team (and any other interested committee member). Editors have to plan those reviews so as to have the comments fully integrated in the draft before the face to face meeting (a period of one week is generally given for reviewing a document and providing comments but the editors and editorial team may agree on a different length during the calls).

Between the spring technical face to face and the publication for public comments

This period is devoted to the integration of comments from the spring face to face in order to have the document ready for publication for public comments. By the date set during the face to face, the document should be completed with possible open issues that during the face to face the committee agreed on submitting for public comments.

There should be no need to organize a call between the spring face to face and the publication for public comments. Any issue with the document should be settled during the spring face to face meeting. In special cases a call may be used to review extensive changes recommended during the face to face meeting.

Between the publication for public comments and the end of the public comments period

There isn't much to do until the public comments period ends. It is however recommended to get a little ahead by regularly going to the IHE forum to treat the comments as they arrive.

Between the end of the public comments period and the summer technical face to face meeting

This period is devoted to treat the comments received and update the document accordingly. So as to do it, a spreadsheet including all the comments received should be created by the editor. Each comment in the spreasheet should be:

• resovled and the document should be updated accordingly;
• not resolved and the issue will be presented to the committee during the summer face to face by priority.

At least one review of the spreadsheet, of the resolution of comments and of the prioritization of the unresolved comments should be done by the editorial team prior to the summer face to face (probably through e-mail but possibly during a call if the author and the editorial team manage to find a slot). The aim is to resolve as much of the comments as possible and to analyze the unresolved comments to present to the committee during the summer face to face for decision (if at all possible, the unresolved comments should be presented as a decision between alternatives with advantages and drawbacks outlined for each alternative). The comments will be treated by the order of priority defined by the editor. The priority should be defined to present the more difficult and/or impactful comments first.

Between the summer technical face to face meeting and the final publication of the profile

This period is devoted to the integration of comments resolution from the summer face to face in order to have the document ready for final publication. By the date set during the face to face, the document should be completed and ready for final publication.

There should be no need to organize a call between the summer face to face and the final publication. Any issue with the public comments should be settled during the summer face to face meeting. In special cases a call may be used to review extensive changes recommended during the face to face meeting.

Support

Mentor

Each first time editor will be provided with a mentor. A mentor is technical committee member experienced in writing a white paper. The mentor will help the editor with any issue about the process of writing a white paper. Any questions on issues like process, template, how to handle a call or any other question not connected to the content of the white paper should be directed to the mentor who will do his/her best to provide an answer.

Editorial Team

For each white paper, an editorial team will be defined during the fall technical face to face meeting. An editorial team is a group of technical committee members interested in the white paper. Each member of an editorial team is committed to review the drafts of the white paper as needed (at least as often as presented in the "Position in the cycle and milestones" section) and provide the editor with input concerning the content of the white paper.

Guidance on tools usage

Guidance on tools usage like how to upload documents on the ftp or update the wiki can be found there. Please read the ftp guidelines and the wiki guidelines before using those tools.

Also be aware that including "space" characters in the name of files uploaded on the ftp may lead to issues for downloading the files. "Spaces" characters (i.e. " ") in file names should be replace by the "underscore" character (i.e. "_" ).

wiki and FTP updates

FTP

The FTP is used to provide various materials for review or publication:

• Drafts and Additional material: In the ITI section of the FTP, under the current year, there is a Technical_Cmte folder in which there is a Whitepaper_Work folder including a folder for each white paper. Each draft and any additional material should be uploaded there during the year. The profile author is encouraged to organize subfolders below the profile folder as they wish. All shared material related to the profile should be placed within the profile folder, including presentations, background documents, working drafts and security risk spreadsheets.
• Public comments version: In the ITI section of the FTP, under the current year, there is a Technical_Cmte folder in which there is a PublicCommentSupplements folder. The version for public comments publication should be uploaded there.
• Final version: In the ITI section of the FTP, under the current year, there is a Technical_Cmte folder in which there is a TrialImplementationSupplements folder. The version for final publication should be uploaded there (though technical white paper are not trial implementation supplements, it is easier for the sponsor handling the publication process to have all documents in the same folder).
• Support materiel: Generally white paper don't need support material as they don't deal with implementation. However, some white papers are describing technical issues with enough detail for vendors to test. Those white paper often refered as implementable white paper may benefit form support material. If so, the support material for those white papers should be treated as support material for profile (see support material in the new profil section)
  

wiki

A specific page for each white paper is created in the wiki. This page is for the editor to use. It can for instance be used to describe issues with the white paper, discuss change of scope of the white paper due to analysis of some issue, cooperative work on the writing of sections...

User Handbook

A user handbook is a particular kind white paper aimed at helping users to better understand a specific issue. Please refer to the white paper section of this page for guidance on how to write a user handbook.

Technical Framework

The Technical Framework contains the Final Text version of all profiles. After release as Trial Implementation and successful connectathon testing a profile may be considered for Final Text. If approved the profile supplement is archived and the contents are inserted into the Technical Framework document.

Updating released documents

Released documents are:

• Technical Framework (TF)
• Trial Implementation Supplements
• White Papers and Handbooks

All changes to Trial Implementation Supplements and Final Text Technical Framework documents are made through Change Proposals (CPs). IHE has an agreed CP process documented on the Change Proposal process page. The ITI committee maintains a CP specific page by year which is linked from the Main ITI Technical Committee page. The 2009 page is named ITI Change Proposals 2009.

Changes to released White Papers and Handbooks are made at increments as requested by the author and user community. New versions are approved by the committee prior to release.

Meetings

There are several meetings (either face to face meetings or tele-conferences) during the cycle for the ITI domain. Though the number of face to face meetings is set, tele-conferences may be organized as needed. This section describes the meetings that are always held each cycle, tele-conference meetings may be added to them as needed during the cycle.

Planning face to face meeting

(around October-November)

Input:

• Proposal for each proposed new work item (profile or white paper).
  

Goal:

• Based on an analysis of the proposals and the technical committee capacity, if needed to refine the scope of each work item and to define a prioritized short list in terms of new work items (profiles and white papers).
  

Output:

• Prioritized short list of proposed new work items (profiles and white papers) for the technical committee.
  

Fall technical face to face meeting of the cycle

(around November-December)

Input:

• Prioritized list of proposed new work item from the planning committee.
• Detailed proposal for each proposed new work item (profile or white paper) selected by the planning committee with a list of alternatives for the standards that can be used for the profile and if relevant for the white paper.
  

Goal:

• Based on an analysis of the detailed proposals and the planning committee priorization, to define recommandations for the coming cycle in terms of new work items (profiles and white papers) and their final scope (use cases to be addressed for new profile, detailed scope for white paper). For each new work item to identify an editor, an editorial team and if needed a mentor.
  

Output:

• Written recommandation to the planning committee.
  

Final decision on new work items tele-conference

(december)

Input:

• Prioritized list of proposed new work item from the planning committee.
• Written recommandation from the technical committee.
• Detailed proposal for each proposed new work item (profile or white paper) selected by the planning committee with a list of alternatives for the standards that can be used for the profile and if relevant for the white paper, the final scope, the name of the editor, the list of name for the editorial team and if needed the name of the mentor.
  

Goal:

• Based in the input from both committee, to define the final list of new work item that the ITI domain will address during the coming cycle.

Output;

• List of the new work items to be adressed during the coming cycle
  

Winter technical face to face meeting of the cycle

(around January-March)

Input:

• For each work item (profile or white paper), a document started with the proper IHE template properly applied;
• For each profile, a rough cut of volume 1;
• For each white paper, a detailed outline with identification of the name and the future content of each section;
• For each profile and for each white paper for which it is relevant, a list of alternatives for standards to be used for the profile with strengthes and weaknesses of each alternative.
  
• Criteria for selection of standards based on requirements and use cases of the profile

Goal:

• For each profile, review of all the use cases and selection of the standards to be used in the profile;
• For each white paper, review of the outline and if relevant selection of the standards.

Output:

• For each profile, selection of standards is complete or, in special cases, a plan for selection of standards is agreed
• For each profile, an action plan to complete volume 1 through calls based on the use cases reviewed during the meeting and calls to review an initial draft of volume 2;
• For each white paper, an action plan to complete the identified sections through calls.

Spring technical face to face meeting of the cycle

(around April-May)

Input:

• For each profile, volume 1 completed (reviewed at least twice by the editorial team prior to the face to face);
• For each profile, volume 2 fully written (each transaction described, Security Considerations written...) and ready to be reviewed by the committee (reviewed at least twice by the editorial team prior to the face to face);
• For each white paper, draft of the white paper with possible open issues (reviewed at least once by the editorial team prior to the face to face).
  

Goal:

• For each profile, review of volume 2 and preparation for public comment publication;
• For each white paper, review of the draft and preparation for public comment publication.
  

Output:

• For each work item (profile or white paper), an approved document to be released for public comment publication possibly pending minor updates to be completed before the release date.
  

Summer technical face to face meeting of the cycle

(during July)

Input:

• For each work item (profile or white paper), a complete document updated with resolution from non-controversial comments (possibly done through call(s) with the editorial team);
• For each work item (profile or white paper), an ordered list of non-resolved comments sorted by priority.
  

Goal:

• For each work item (profile or white paper), resolution of comments and preparation for final publication.
  

Output

• For each work item (profile or white paper), an approved document to be released for final publication possibly pending minor updates to be completed before the release date.
  

Return to ITI Technical Committee

See Also

IHE Process Page