use of UML vs ExampleScenario #4
Comments
|
ExampleScenario is not a replacement for UML diagrams, but a way to get those diagrams. |
|
Although I agree that ExampleScenario and UML are not equivalent, I also agree that ExampleScenario is too immature at the moment. I would suggest going forward using UML supplemented by various other "pieces" rather than wait until ExampleScenario is complete and mature enough to encapsulate all our needs. |
|
There are 2 different things:
Assuming the point is about examples, there are currently at least 4 ways to generate diagrams:
Options 1 and 2 are never excluded - we can do that now and keep doing that later. Option 3. uses the standard mechanism and adds the FHIR built-in verification. I have the transformation tools, and I could use them in this template, but we always go back to not requiring people to use additional java tools. Option 4 is a custom format that requires tools, which I'd say is not mature. In any case, I don't see which of our needs are missing in ExampleScenario... Which ones? |
|
A UML Diagram is but a part of wider documentation. If you just generate UML but no text to go with it, you've communicated poorly and only about 1/3 of the audience will get any of what the diagram is trying to convey. There needs to be text to go along with what the diagram communicates, and parts of that text are associated with different parts of the diagram. Thus, a larger structure can be used to represent the content. Such a structure can be used to generate both the diagram and the accompanying content. I spend about a week coming up with a model that can work and be used to generate sequence diagrams (one type of UML) for use cases in Volume 1. I spent another week working on a structure for Transactions in Volume 2, which includes the UML, and a lot of the volume 2 content. These were purpose-build XML structures not informed by ExampleScenario, built iteratively to document IHE profile content for use cases in volume 1, and transactions in volume 2. I can (and did in about 15 minutes) map the element of that custom XML in SANER projects to ExampleScenario with a one-to-one, and onto mapping (in other words, a reversible mapping) meeting the syntax and semantics of ExampleScenario. I cannot do quite the same with ExampleScenario for volume 2 content, as ExampleScenario is missing content to support some of the details we use to describe content with sufficient detail to generate things like CapabilityStatements (which I've managed to automate). ExampleScenario however, is close to what is needed, but there's a lot more detail in a transaction than there is in a use case. I'd go with option 3 for a long term approach, and I wouldn't limit it to using ig-publisher based tools, because those require working with things like Jekyll which right now still have inconsistent results (e.g., bugs) when applied to things with any complexity. As for the immaturity of ExampleScenario, I don't find that to be a handicap. It perfectly fits use cases as we use them, it's pretty close to what we need for a lot of transaction, and we should be able to INFORM what happens to it as it matures, AND help establish the maturity desired. |
|
I understand the desire to have one artifact (keith magic xml, Jose ExampleScenario) that produces many narrative, graphics, and artifacts... This has a nice benefit of write once, and limits the synchronization of changes. However it has a huge drawback of being a single purpose mechanism. That is to say that Keith understands his xml and his xslt really well, but no one else does. Jose understands ExampleScenario, but no one else does. Yes others can learn, as evidence by Keith last message in this thread. But that doesn't increase the population of people that understand the mechanism by much. Where as editing in MarkDown, graphics in UML, even test scripts in Cucumber, are all mechanisms that are used in the wider engineering community. Thus there is much more likelihood that someone can come in and use them; or do corrections upon them. I am for #2. Surely for the short-term, but likely for the medium term too Long-Term - I am more for identifying that we (IHE) have a need, we have a solution, and working with HL7 on a consensus solution that both HL7 and IHE use for this challenge. I recognize that HL7 might choose the ExampleScenario solution, but if they do then they have addressed my first concern as at that point more than Jose will understand ExampleScenario. A concern I have with ExampleScenario is that it is not useful only for the abstract example scenario used to drive the profile definitions of actors, transactions, and interactions. I believe it is also useful for expressing alternative flows, edge cases, failure-modes, etc... as such using it does mean that one needs to express to the IG build which instance is for the abstract (logical) model; and which are for abstract (logical) options or optional flows; and which are simply there for testing support. |
|
ExampleScenario a standard resource, and it's not a steep learning curve
to make one. The FHIR toolkit even has a simple editor where we can edit
ExampleScenarios (your bug-free mileage may vary).
ExampleScenario is not at all intended to capture actors, transactions,
interactions.
For the long-term, that is why I created the other repo - I will populate
it as soon as time allows.
Kind regards
José
…On Fri, Jun 12, 2020 at 5:54 PM John Moehrke ***@***.***> wrote:
I understand the desire to have one artifact (keith magic xml, Jose
ExampleScenario) that produces many narrative, graphics, and artifacts...
This has a nice benefit of write once, and limits the synchronization of
changes. However it has a huge drawback of being a single purpose
mechanism. That is to say that Keith understands his xml and his xslt
really well, but no one else does. Jose understands ExampleScenario, but no
one else does. Yes others can learn, as evidence by Keith last message in
this thread. But that doesn't increase the population of people that
understand the mechanism by much.
Where as editing in MarkDown, graphics in UML, even test scripts in
Cucumber, are all mechanisms that are used in the wider engineering
community. Thus there is much more likelihood that someone can come in and
use them; or do corrections upon them.
I am for #2 <#2>. Surely
for the short-term, but likely for the medium term too
Long-Term - I am more for identifying that we (IHE) have a need, we have a
solution, and working with HL7 on a consensus solution that both HL7 and
IHE use for this challenge. I recognize that HL7 might choose the
ExampleScenario solution, but if they do then they have addressed my first
concern as at that point more than Jose will understand ExampleScenario.
A concern I have with ExampleScenario is that it is not useful only for
the abstract example scenario used to drive the profile definitions of
actors, transactions, and interactions. I believe it is also useful for
expressing alternative flows, edge cases, failure-modes, etc... as such
using it does mean that one needs to express to the IG build which instance
is for the abstract (logical) model; and which are for abstract (logical)
options or optional flows; and which are simply there for testing support.
—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub
<#4 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AD3HUUCR5FDHDCIBUWGNB5TRWJFUTANCNFSM4MECCGGA>
.
|
|
do we need to choose? Can we support/recommend use of UML and ExampleScenario? Might we only need to differentiate between the two? |
|
If the question is about use of UML vs ExampleScenario, I don't see a
choice between plantuml ( a tool) and examplescenario (a resource).
We're working on making support for PlantUML in the templates.
…On Wed, Jul 8, 2020 at 6:18 PM John Moehrke ***@***.***> wrote:
do we need to choose? Can we support/recommend use of UML and
ExampleScenario? Might we only need to differentiate between the two?
Are either of these supported in the build tools? I have not been able to
figure out how to get UML code to render, so have been saving the
image-source and doing my own rendering with plantuml.
—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub
<#4 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AD3HUUE2ZEFN4IY2TQTN6F3R2SL5LANCNFSM4MECCGGA>
.
|
|
ihe-fhir wg discussed this and concluded that UML diagrams should be sourced in PlantUML code syntax or ExampleScenario. |
It is agreed that using UML diagrams is sufficient today, where it might be possible that a future design might leverage or enable use of ExampleScenario. Today ExampleScenario is too immature and too difficult for the typical IHE author to use effectively.
Please comment
The text was updated successfully, but these errors were encountered: