HL7 2024-Jan: Evaluate Readability and the use of Version Note boxes and Placeholders for Future Content

[ToddCooper]

Section Number

Entire SDPi specification

Priority

• Low: Typo or other minor classification that an editor can manage. Requires no group discussion.

Issue

HL7 JAN2024 Ballot Comment: OTHER-2773 "Eliminate forward and backward-looking content.".

I struggle with forward looking statements and content in standards documents. Personally, I feel that we should document the situation as it is, and not as it will be. Similarly, it doesn't matter what previous releases looked like, only the current one. We have issue trackers and work item selection processes for future work. Consider recasting the document throughout to only focus on current capabilities and leave out forward and backward looking statements.

Proposed Change

SDPi Editorial team should review the document in its entirety and consider both the value of including "Version Notes" (e.g., placeholder sections that will be expanded in a future version) and place-holder sections themselves. 

[ToddCooper]

SDPi Friday 2024.04.12 - Assignees will have a discussion to review issue and possible opportunities to improve readability. ALSO this is a key topic on the Guidance for the HL7 MAY2024 ballot - there should be some feedback by the Dallas May meetings.

[ToddCooper]

SDPi Friday 2024.04.26 Discussion

1. Added agenda item to May HL7 WGM to review HL7 SDPI Ballot Jira tickets (including this one)
2. Not an easy task ... a lot of work NOW and would have to be reversed later
3. Proposal: Hide text that is forward looking ... but IS helpful for readers
4. Proposal: (In an HL7 Jira ticket resolution) Provide briefing webinar for how to review the SDPi specification

[JavierEspina]

Here is an additional proposal to complement the two added on Apr 26 (comment above):

• Add a clearly visible "Informative" stamp next to / below the title of those sections that are placeholders or do not yet contain requirements

Examples of sections with such "Informative" stamp would be:

• 1:2.3.13 Service-oriented Device Point-of-care Interoperability - External Control (SDPi-xC) Profile
• 1:12.2 SDPi-A Actor Options
• 1:13 SDPi-X Profile
• All sections in 3:8.7 Device specialization content modules, except for 3:8.7.3 Device: Physiologic monitor
• All sections that describe actors that are labelled as "deferred" in overview tables (note that "deferred" transactions have no related sections)
• The appendixes (such as 1:A and 1:C) that are already identified as informative in a "SDPi Supplement Version Note"

[ToddCooper]

@JavierEspina Perhaps a good "scoping" heuristic - what future looking items are relevant for the 3.0 MVP spec, and which are beyond that and should be considered for removal (or at least hiding from the rendered specification).

Some is pretty obvious, such as the "RI" and MBSE+SysML 2.0 objective. I still don't have a clue WHEN .2.0 will be a reality, and we may end up borrowing their "requirements modeling" data structures to inform our AsciiDoc elements, BUT MBSE+SysML 2.0 is a stretch and should be relegated to aspirational text (or footnote!).

Perhaps once we have the RI integrated + Discovery Proxy ... both in 1.4 ... we can then schedule a walkthrough and identify what should be either MARKED (if it is MVP targeted) or removed / hidden.

[ToddCooper]

SDPi Friday 2024.08.02 -
Reviewed previous 2-3 comments.
Regarding SDPi-xC - per the "heuristic" should it be removed completely? Todd pointed out that a basic external control may be included in the MVP specification release 3.0 mid-2025, though the 11073-10703 Control PKP will not be ready until late 2025 or 2026.

[JavierEspina]

SDPi Developers & Testers Workshops #4 -

• hide (from render) concept sections 1:10.4.1.3 thru 1:10.4.1.10
• find 2024 references and update appropriately