OASIS Darwin Information Typing Architecture (DITA) TC

Hi, DITA TC colleagues.   I am designing information architecture and markup for some Mayo content. It’s a library of content called “Ask Mayo Expert,” and the targeted audience is clinicians. Some of the simplest content is about particular medical condition, for example, bipolar disorder. Here is a screen capture of how the content is currently presented:   Here’s an explanation of the areas that I’ve marked: Navigation of the publication, easily handled with a DITA map that references topics such as “Symptoms (adult).” As a user clicks on different nodes in the navigation, what is displayed in the central pane changes – but the top navigation pane (include #2) does not change. Links that are hand-curated by subject matter expert. The items grouped under “Guidelines & Resources” tend to be links to external web sites, and the items grouped under “Patient Education” tend to be PDFs developed by Mayo patient education specialists for different branches of the clinical practice at Mayo. These links are applicable to ALL of the “Bipolar disorder” content.   I, of course, immediately thought of expressing these relationships with a <reltable>. But when I looked through the spec, it was pretty clear that all our element-reference topics are written with focus on using relationship tables to define relationships between individual topics, rather than relationships between a publication and external links.   A couple of questions: Are we being too old-school in how we define relationship tables in the spec? There will be custom processing (of course) for the Mayo DITA source, so from that perspective, I can broaden the usage of a relationship table. But I am urging that all Mayo transformations begin with using base DITA-OT transformations. Might I be better off with a specialized DITA map that had specific structures for “Guidelines & Resource” and “Patient Education,” rather than using a relationship table?   Thoughts very much welcome.   Kristen James Eberlein Content Engineer Health Education & Content Services 507-293-0006 eberlein.kristen@mayo.edu My pronouns are she/her/hers.  

Hi -- My 2 cents. If you plan to be the person who updates all the reltables in perpetuity, then using <reltable>s probably makes sense. If writers who you do not know will be updating/maintaining them, it's more of a crap shoot. Some writers easily grok the logic, many do not. A specialized DITA map may be the way to go from a maintenance point of view. Stan On Thu, Dec 21, 2023 at 11:23 AM Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Hi, DITA TC colleagues. I am designing information architecture and markup for some Mayo content. It s a library of content called Ask Mayo Expert, and the targeted audience is clinicians. Some of the simplest content is about particular medical condition, for example, bipolar disorder. Here is a screen capture of how the content is currently presented: Here s an explanation of the areas that I ve marked: Navigation of the publication, easily handled with a DITA map that references topics such as Symptoms (adult). As a user clicks on different nodes in the navigation, what is displayed in the central pane changes but the top navigation pane (include #2) does not change. Links that are hand-curated by subject matter expert. The items grouped under Guidelines & Resources tend to be links to external web sites, and the items grouped under Patient Education tend to be PDFs developed by Mayo patient education specialists for different branches of the clinical practice at Mayo. These links are applicable to ALL of the Bipolar disorder content. I, of course, immediately thought of expressing these relationships with a <reltable>. But when I looked through the spec, it was pretty clear that all our element-reference topics are written with focus on using relationship tables to define relationships between individual topics, rather than relationships between a publication and external links. A couple of questions: Are we being too old-school in how we define relationship tables in the spec? There will be custom processing (of course) for the Mayo DITA source, so from that perspective, I can broaden the usage of a relationship table. But I am urging that all Mayo transformations begin with using base DITA-OT transformations. Might I be better off with a specialized DITA map that had specific structures for Guidelines & Resource and Patient Education, rather than using a relationship table? Thoughts very much welcome. Kristen James Eberlein Content Engineer Health Education & Content Services 507-293-0006 eberlein.kristen@mayo.edu My pronouns are she/her/hers.

Fundamentally a row in a relationship table does nothing more than relate a set of resources addressed via topicrefs to each other with some semantic imposed by the table.

Given that, I think you are free to impose whatever meaning you want to those relationships, including publication-to-supporting-artifact .
 
If your publication is defined by map root-01.ditamap , you could do something like:

<map><title>Root One</title>
 
  <mapref keys= publication scope= peer keyscope= root-01 href= >
  <reltable outputclass="publication-to-supporting-artifact">
    <relheader>
      <relcolspec><topicmeta><navtitle>Publication</navtitle></topicmeta></relcolspec>
      <relcolspec><topicmeta><navtitle>Supporting Docs</navtitle></topicmeta></relcolspec>
    </relheader>
   <relrow>
      <relcell>
       <topicref keyref= root-01.publication >
          <topicmeta><navtitle>Root One</navtitle></topicmeta>
       </topicref>
     </relcell>
      <relcell>
          <topicref scope= external format= pdf href= href= https://example.com/docs/some-doc.pdf >https://example.com/docs/some-doc.pdf >
             <topicmeta><navtitle>Some Doc</navtitle></topicmeta>
          </topicref>
      </relcell>
   </relrow>
  </reltable>
</map>
 
Here I m using a peer mapref with a @keys value to represent the publication as a whole, which I think is legit even though we don t explicitly describe this use of peer maprefs in the spec. But a peer mapref
explicitly means the target map is a root map , so I think being able to address the root map in this way is clear and meaningful.
 
So this reltable relates the publication root-01 to the PDF document some-doc.pdf .

 
It might make more sense for this reltable to be in a root map of its own that does nothing but define these relationships and then use that as input to your custom publication process.
 
This whole use of reltables assumes that the set of supporting docs will be different over time or in different use contexts for the same publication.
 
Cheers,
 
E.
 


_____________________________________________
Eliot Kimber
Sr Staff Content Engineer
O: 512 554 9368
M: 512 554 9368
servicenow.com


LinkedIn     Twitter     YouTube     Facebook
 



From:
dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Date: Thursday, December 21, 2023 at 10:32 AM
To: DITA Technical Committee (dita@lists.oasis-open.org) <dita@lists.oasis-open.org>
Subject: [dita] FW: Use of relationship tables


[External Email]
 





Hi, DITA TC colleagues.
 
I am designing information architecture and markup for some Mayo content. It s a library of content called Ask Mayo Expert, and the targeted audience is clinicians. Some of the simplest content is about
particular medical condition, for example, bipolar disorder. Here is a screen capture of how the content is currently presented:


 
Here s an explanation of the areas that I ve marked:

Navigation of the publication, easily handled with a DITA map that references topics such as Symptoms (adult). As a user clicks on different nodes
in the navigation, what is displayed in the central pane changes but the top navigation pane (include #2) does not change. Links that are hand-curated by subject matter expert. The items grouped under Guidelines & Resources tend to be links to external web sites, and the
items grouped under Patient Education tend to be PDFs developed by Mayo patient education specialists for different branches of the clinical practice at Mayo. These links are applicable to
ALL of the Bipolar disorder content.
 
I, of course, immediately thought of expressing these relationships with a <reltable>. But when I looked through the spec, it was pretty clear that all our element-reference topics are written with focus on
using relationship tables to define relationships between individual topics, rather than relationships between a publication and external links.
 
A couple of questions:

Are we being too old-school in how we define relationship tables in the spec? There will be custom processing (of course) for the Mayo DITA source, so from that perspective, I can broaden the usage of a relationship table. But
I am urging that all Mayo transformations begin with using base DITA-OT transformations. Might I be better off with a specialized DITA map that had specific structures for Guidelines & Resource and Patient Education, rather than using
a relationship table?
 
Thoughts very much welcome.
 
Kristen James Eberlein
Content Engineer Health Education & Content Services 507-293-0006
eberlein.kristen@mayo.edu
My pronouns are she/her/hers.
 

I d agree - well within expected usage, you can even set format and scope as defaults for the column if you want On Thu, Dec 21, 2023 at 11:56 AM Eliot Kimber < eliot.kimber@servicenow.com > wrote: Fundamentally a row in a relationship table does nothing more than relate a set of resources addressed via topicrefs to each other with some semantic imposed by the table. Given that, I think you are free to impose whatever meaning you want to those relationships, including publication-to-supporting-artifact . If your publication is defined by map root-01.ditamap , you could do something like: <map><title>Root One</title> <mapref keys= publication scope= peer keyscope= root-01 href= > <reltable outputclass="publication-to-supporting-artifact"> <relheader> <relcolspec><topicmeta><navtitle>Publication</navtitle></topicmeta></relcolspec> <relcolspec><topicmeta><navtitle>Supporting Docs</navtitle></topicmeta></relcolspec> </relheader> <relrow> <relcell> <topicref keyref= root-01.publication > <topicmeta><navtitle>Root One</navtitle></topicmeta> </topicref> </relcell> <relcell> <topicref scope= external format= pdf href= href= https://example.com/docs/some-doc.pdf target= _blank >https://example.com/docs/some-doc.pdf > <topicmeta><navtitle>Some Doc</navtitle></topicmeta> </topicref> </relcell> </relrow> </reltable> </map> Here I m using a peer mapref with a @keys value to represent the publication as a whole, which I think is legit even though we don t explicitly describe this use of peer maprefs in the spec. But a peer mapref explicitly means the target map is a root map , so I think being able to address the root map in this way is clear and meaningful. So this reltable relates the publication root-01 to the PDF document some-doc.pdf . It might make more sense for this reltable to be in a root map of its own that does nothing but define these relationships and then use that as input to your custom publication process. This whole use of reltables assumes that the set of supporting docs will be different over time or in different use contexts for the same publication. Cheers, E. _____________________________________________ Eliot Kimber Sr Staff Content Engineer O: 512 554 9368 M: 512 554 9368 servicenow.com LinkedIn Twitter YouTube Facebook From: dita@lists.oasis-open.org < dita@lists.oasis-open.org > on behalf of Kristen James Eberlein < kris@eberleinconsulting.com > Date: Thursday, December 21, 2023 at 10:32 AM To: DITA Technical Committee ( dita@lists.oasis-open.org ) < dita@lists.oasis-open.org > Subject: [dita] FW: Use of relationship tables [External Email] Hi, DITA TC colleagues. I am designing information architecture and markup for some Mayo content. It s a library of content called Ask Mayo Expert, and the targeted audience is clinicians. Some of the simplest content is about particular medical condition, for example, bipolar disorder. Here is a screen capture of how the content is currently presented: Here s an explanation of the areas that I ve marked: Navigation of the publication, easily handled with a DITA map that references topics such as Symptoms (adult). As a user clicks on different nodes in the navigation, what is displayed in the central pane changes but the top navigation pane (include #2) does not change. Links that are hand-curated by subject matter expert. The items grouped under Guidelines & Resources tend to be links to external web sites, and the items grouped under Patient Education tend to be PDFs developed by Mayo patient education specialists for different branches of the clinical practice at Mayo. These links are applicable to ALL of the Bipolar disorder content. I, of course, immediately thought of expressing these relationships with a <reltable>. But when I looked through the spec, it was pretty clear that all our element-reference topics are written with focus on using relationship tables to define relationships between individual topics, rather than relationships between a publication and external links. A couple of questions: Are we being too old-school in how we define relationship tables in the spec? There will be custom processing (of course) for the Mayo DITA source, so from that perspective, I can broaden the usage of a relationship table. But I am urging that all Mayo transformations begin with using base DITA-OT transformations. Might I be better off with a specialized DITA map that had specific structures for Guidelines & Resource and Patient Education, rather than using a relationship table? Thoughts very much welcome. Kristen James Eberlein Content Engineer Health Education & Content Services 507-293-0006 eberlein.kristen@mayo.edu My pronouns are she/her/hers.