Authoring guidance for Content Tracker issues

Please note this page is in draft at present and input to assist with improving this guidance is welcome. Please send any comments to @Cathy Richardson.

Considerations before commencing construction

An IHTSDO Content Tracker issue must be approved for construction by the Head of Terminology prior to construction in the Authoring Platform commencing.
External authors need to liaise with an internal member of the SNOMED International Content team for both the construction approval and authoring work.
Development of a construction plan - see below
The criteria developed by the 2014 cohort for the construction and transition phases: Construction_Transition Phase Criteria

Background: Authoring Platform

The IHTSDO Authoring Platform is designed to enable a number of authors to undertake authoring tasks at the same time. To support this, the platform uses a project based approach, with projects set up for different areas of work e.g. Customer Requests, Anatomy Project and Content Trackers. Within each project, authors set up tasks to complete an item of work relating to the relevant project. Further information on the way the Authoring Platform is set up may be located in the User Guide on Project Branches, Task Branches and Rebasing

There are a number of authors actively involved in content development and as a result changes are occurring in the terminology on a daily basis during an authoring cycle. Given the amount of work being undertaken and complexity of the terminology it is important that an author keeps all their tasks updated with the current content (rebase) and also shares the changes they have made with others in a timely manner. To support this an authoring task should not contain too many changes (around 10-15) and should not be kept open for too long (about a week is recommended).

Given the extent of changes occurring, where an author does not rebase, finalise and promote the content in a task in a timely manner they risk the content in their task being too out of sync with the content within a project. This may result in a number of content merges which may in turn require significant effort to resolve. Depending on the extent of the merge issues a task may get to a point where it cannot be promoted and the work then needs to be redone in a fresh task.

Projects also require regular (usually a minimum of once a day) rebasing and promotion so that changes made across the projects are shared. This is managed by the internal team member who leads that project.

Each release a new project will be set up in the authoring platform for the authoring of content trackers. Please ask for the name of the project for use (and access if you don't have it) for the release you are working on, prior to starting. Whilst noting this, depending on the nature/extent of changes for a tracker, at times a separate project might be established so that it can be promoted when needed.

Development of Construction Plan

Content tracker issues often impact a number of concepts. Where this is the case an author will need to create and work in several tasks within the Content Tracker project in the Authoring Platform to construct the solution. Given this and the complexity of the terminology it's recommended that the construction work be planned out before commencing.The following points are guidelines to assist with development of a plan:

Identify which concepts need to be changed, added, inactivated etc.
- Please note while queries may be run in an authoring task, at present this information can not be extracted or transferred to other tasks.
- If you are unable to run a query, requests may be submitted to Techsupport@snomed.org
Set up a mechanism to keep track of the work. Suggestions include:
- CRS tickets
- Excel spreadsheet
- Detailed plan in the inception and elaboration document.
Determine an approach - see below
Each task should be limited:
- in size (around 10 -15 concepts each); and
- in the length of time it remains open before sending for review. About a week is recommended, with a maximum of two weeks.
  - Tasks open longer than two weeks cannot be guaranteed to successfully rebase and this could result in re-work.
  - It's recommended you regularly rebase your task as you undertake the work.
Work on tasks sequentially or limit the number of tasks you work on concurrently as changes in one task will not be reflected in another task until the first task is promoted to a project level and the second task is rebased.
- Where you have dependencies across tasks one strategy that may be employed is finishing the first task and promoting it to the project, then rebasing the second task to get those changes to continue the authoring of the solution.
Provide access to your plan to the reviewer so they are aware of work yet to be undertaken.
- Where feasible, one reviewer will be responsible for reviewing all the tasks related to a particular content tracker issue.
At the end of the construction process (and all tasks have been promoted to a project level), review the changes in the TS Browser: https://authoring.ihtsdotools.org/browser/ at a project level and/or run queries to ensure the changes made have resulted in the expected outcome.
- This is especially important when working with primitive concepts.

Suggestions for approaches

Review the content to determine the inter-relationships between concepts, hierarchies.
- If possible consider working in one sub-hierarchy or focus area at a time e.g. all the rubella disorder concepts.
Making the changes to the target value hierarchies:
- Create the new values before working on your area of content.
- If inactivating the concepts used as the target values e.g. |Unilateral left|, these should be inactivated after the changes to the source concepts have been made.
For hierarchies with a concept model, have a model for each type of content change so you can ensure the stated view is correct even if the inferred view does not appear so (until far enough though the work).
From experience so far, a top down approach has been determined to work better than a bottom up approach in most cases.
- This may exclude the top level concepts in your area of work. They should usually be done towards the end of the work.
- Be aware that changes may make some concepts that should be in a parent-child relationship, siblings until changes are made to both.
- With inactivating an area of content e.g Unilateral situation concepts, a bottom up approach may be preferred.
Pattern 11 in the QA report which shows existing sufficiently defined concepts that gained a stated intermediate primitive parent and lost active inferred descendant(s) may assist in determining the impact of changes.
While many changes will require manual authoring, some processes that may be feasible given the current tooling are:
- A batch change using a batch spreadsheet
- Automation of a change

Factors to consider in determining the feasibility include:

- - Current tooling functionality
  - Tech Support resources requirements and availability.
    - While a simple query is feasible via a support desk request, more extensive resources would require prioritisation and approval from the Heads of Content and Technical Services.
  - Volume of changes
  - Types of changes
  - Impact of changes
  - Risk of generating conflicts/merges in the Authoring Platform
  - Benefits of using the approach e.g. time, resources, consistency of change etc