IHE ITI XDStar Volume 3, Section 4 Redocumentation Debrief Gila Pyke Lead Facilitator/Cognaissance

Agenda Review focus group feedback Gather additional feedback to Volume 3, Section 4 Present redocumentation progress so far and how it addresses focus group learnings –Obtain additional direction Next steps

Focus Group Feedback

F1 - In most cases, expanding the number of examples and detailed definitions would assist those working with the documentation understand some of the nuances. For example, for queries on metadata, specify for each metadata field details about the process and results for responding to that query. F2 - There needs to b a detailed definition for all metadata fields that includes what they can/may contain (with examples). F3 - In all cases, it is important to ensure that example data in metadata fields is clearly marked as an example (e.g., “exampleCode”) so that it can be easily differentiated from required field contents or potentially say “in this example replace 'theDocument' with the actual document details”.

Focus Group Feedback F4 - Definitions of Document, Document Entry, Submission Set and Folder needs to be earlier in the document. For clarity, knowing what something is before being told how it is used/requested, etc. is helpful. F5 - Business context for when or how something is used (this X would be used when you re doing Y) are needed for sections where it isn't obvious. F6 - For metadata concepts like displayName that are common to all metadata attributes, just skip the definition and make a statement that “all codes are mandated to have display names”

Focus Group Feedback F7 - Summaries of what is in referenced documents/other volumes as well as link information are needed to ensure ease of use. Section specific feedback was also provided, please see slide ## for details

Responses and Resolutions

Focus Group Feedback and Responses F1 - In most cases, expanding the number of examples and detailed definitions would assist those working with the documentation understand some of the nuances. For example, for queries on metadata, specify for each metadata field details about the process and results for responding to that query. –The sections for DocumentEntry, Submission Set and Folder metadata have been completely restructured and expanded to give more detailed definitions and examples. –This expanded format also provides detail as to how the information is to be structured. However, query matching rules are part of Volume 2 and outside the scope of Volume 3, Section 4

Volume 3, Section 4 Reorganization Additional high level explanations Additional details and examples for each metadata attribute All original content from volume 3, Section 4 has been maintained. Content as been re- ordered, additional explanatory text and examples provided (~35 pages so far)

Focus Group Feedback and Response F2 - There needs to be a detailed definition for all metadata fields that includes what they can/may contain (with examples). –Detailed definitions for metadata fields, what they may contain as well as examples have been added to the new section –New format provides old “summary tables” as well as examples and details for each metadata attribute for those who need them.

Focus Group Feedback and Response F3 - In all cases, it is important to ensure that example data in metadata fields is clearly marked as an example (e.g., “exampleCode”) so that it can be easily differentiated from required field contents or potentially say “in this example replace 'theDocument' with the actual document details”. –Done. A complete edit of all examples was executed and metadata that was replaceable were marked as examples (e.g., “IDExample_54” or "ExamplepracticeSettingCode")

Focus Group Feedback and Response F4 - Definitions of Document, Document Entry, Submission Set and Folder needs to be earlier in the document. For clarity, knowing what something is before being told how it is used/requested, etc. is helpful. –Done. –Abstract metadata model section added to the beginning provides definitions and descriptions of these object types and their characteristics.

Focus Group Feedback and Response F5 - Business context for when or how something is used (this X would be used when you are doing Y) are needed for sections where it isn't obvious. –TBD – need help determining what types of examples could help resolve this

Focus Group Feedback and Response F6 - For metadata concepts like displayName that are common to all metadata attributes, just skip the definition and make a statement that “all codes are mandated to have display names” –Done, automatic metadata like “displayName” are no longer defined in each instance.

Focus Group Feedback and Response F7 - Summaries of what is in referenced documents/other volumes as well as link information are needed to ensure ease of use. –In progress. Where possible, codes are linked to specific section numbers (e.g., HL7 V2 Chapter 2a Section 89)

Focus Group Feedback and Response Section Specific Feedback 1.Table has a confusing title. 2.Table should be moved after tables to Table simplify definitions in the table, do more of leaving details about attributes to separate section. 4.Section improve the definition of contentTypeCode, including real world examples. Also improve format code 5.Section was suggested to be elevated to it's own section. 6.The location of how to convey the order of the submission set was not easily located 7.The first sentence of was seen as a note and should be moved down within the section 8.The tables in are sometimes not clear enough. For example, it says “Issuing Authority”.. two words are insufficient 9.Section needs to be more specific on how enforcement is affected and what the enforcement is based on (e.g., ebXML Section X) 10.Needs to be clear wither any part of this section applies to an actor in other profiles, like XCA, XDR, etc. 11.Section is good about defining the data for an error but not about what produces an error 1.To be changed to something more pithy 2.In Progress. The restructuring is complex and new locations are being determined 3.Done 4.Done, each attribute has it's own subsection 5.Done 6.Done 7.TBD 8.Done 9.TBD 10.TBD 11.TBD

Next Steps Remaining working group teleconferences on Feb 21, March 7, possibly March 21 Publish for “pre-public comment” to determine if redoc introduces enough value to publish for public comment If you are interested in participating in either of the above, please

Where to find current materials All current documentation is on the IHE FTP at: ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr /Technical_Cmte/WorkItems/XDStarR edocumentationSupplement