Supplemental Documentation Document

[ryanscholzdvm]

In updating to Version 3, the XSLT transform document that has been used to generate the HTML documentation from the XML standard is no longer working correctly. By adding additional first-level elements (Movement & Sighting), those elements are not appearing in the HTML that is generated. I'm not sure that I understand XSLT enough to be able to update the transform document myself.

Do we want to update the XSLT document and continue generating it with each new update, or move away from the HTML documentation and just rely on the inline documentation within the standard itself?

[mkm1879]

This was admittedly a hack. It was just a work-around to try to make the information in the schema semi-readable by people who don't read XML fluently. I used XSLT just to be sure the word document contained ONLY information present in the normative schema.

So my vote, I think, would be to discontinue it. It MAY be worth periodically revisiting the need for an informative document explaining the contents of the schema in true human-readable English. It would need disclaimers to make clear that the schema is THE standard.

[jconlon]

@mkm1879 Have you tested any of the existing tools found on GitHub? Just found this one.

[ryanscholzdvm]

Another piece that was brought in during today's discussion was whether additional resources such as this, and best practices documents should live on the GitHub or if they should be moved to another location such as a committee page on the USAHA website. Dr. Mudschenk was going to look into that possibility and report back. This also somewhat applies to #59. @mkm1879 discussed the potential for developing some "unofficial" documentation and best practices resources for eCVIs.

[mkm1879]

Not sure if my eCVI "Book" goes here or in #59 I've done some more, mostly small, edits. The "commenter" link to the document on Google Docs is https://docs.google.com/document/d/1j00eqQwB0dWycZfk4Zj12ALttrR2PLTY/edit?usp=sharing&ouid=117212872476935046266&rtpof=true&sd=true

[mkm1879]

I believe we elected to discontinue the XSLT transformed schema in favor of having a non-normative guide. That discussion is now in issue #59 Best Practices Guide

[ryanscholzdvm]

I'm going to reopen this temporarily. #59 is being used to develop the guide, but this issue was really intended to remove the existing documentation from the GitHub. To help keep things straight, it would be helpful to leave this issue open until the 3.1 version is published to link the removal of those documents to the ticket.

[mmcgrath]

We support this inclusion in the Jan 2025 release