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 advices for editing your document. Should they not be enough, you can always ask experienced ITI members:

• 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);
• experienced ITI members.
  

ITI Production cycle

All documents produced by the ITI domain are supporting 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.

Document types

Each document type has its specificities in terms of content and milesstones that are presented in the following sections

Proposal

TBD

Detailed Proposal

TBD

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 (planning committe and first technical committee). 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 is eventually aimed at being integrated in the ITI Technical Framework. Thus the structure of the supplement is following the Technical Framework structure with:

• 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) between the technical actors;
• possibly a volume 3 section describing the content exchanged between the technical actors.
  
  

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

Volume 1

Volume 1 is presenting use cases in the less technical possible way (e.g. clinical scenarios if relevant) describing 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 adviced 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 constrains put on the actors and transactions. Constrains should only be put on actors and transactions for interoperability and/or security reasons, nay other ground for constrains is out of the scope of an IHE profile.

Volume 3

If needed Volume 3 is detailing the content of the exchanges between actors. 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 sections

Security sections are included in Volume 1 and/or Volume 2 after a risk analysis on the profile scope. Guidance for writing the security sections are provided in the Cookbook: Preparing the IHE Profile Security Section

Template
The template to use for writing a profile is on IHE ftp (ftp.ihe.net)

Position in the cycle and milestones
Work on a new profile start 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 decion on work items for the cycle and the second technical face to face meeting

This period is devoted to the writting of the volume 1 section of the profile and a broad assesment of the standards for the volume 2 section. By the second 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 second technical face to face meeting
• The remaining of volume 1 section (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 strenghts 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 second 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 second 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 second face to face meeting and the third face to face meeting

This period is devoted to the integration of comments from the second face to face in the volume 1 section and to the writting of the volume 2 section. By the third 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 section written) with possible open issues clearly listed

At least one T-con on the profile is planned by the technical co-chairs between the second and the third face to face. 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 two reviews of the material for the third 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 third face to face and the publication for public comments

This period is devoted to the integration of comments from the third 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 is no time to organize a call between the third face to face and the publication for public comments. Any issue with the document should be settled during the third 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 possible 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 fourth 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 fourth face to face by priority.

If possible, one T-con on the profile is planned by the technical co-chairs between the end of the public comments period and the fourth face to face. It is very unlikely that a second call can be scheduled as the timeframe is short, but if the editor and the editorial team agree on a time, they can ask for other call(s).

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 fourth face to face (probably through mail but possibly during a call). 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 fourth 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 fourth face to face meeting and the final publication of the profile

This period is devoted to the integration of comments resolution from the fourth 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 is no time to organize a call between the fourht face to face and the final publication. Any issue with the public comments should be settled during the fourht face to face meeting.

Support

Mentor

TBD

Editorial Team

TBD

wiki and FTP updates
TBD

New White Paper

Aim of the document
TBD
Structure of the document
TBD
Template
TBD
Position in the cycle and milestones
TBD
Support

Mentor

TBD

Editorial Team

TBD
wiki and FTP updates
TBD

User Handbook

TBD

Updated Technical Framework

TBD

Existing document

TBD

Face to face meetings

Planning face to face meeting

(around October-November)

TBD

First technical face to face meeting of the cycle

(around November-December)

Input:

• Detail 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, to define recommandations for the coming cycle in terms of new work items (profiles and white papers).
  

Output:

• Written recommandation to the planning committee.
  

Second 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.
  

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, 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.

Third 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 section 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 editoria 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.
  

Fourth 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