Topics

[EXT]: [dita-users] Visualizing reltables


 

Here is documentation I authored for our team to understand textually and visually how the various relationship table links are set up and the resulting links.

 

Mona Ross | Principal Information Architect | Ellucian® | M:+1.304.596.3712 | www.ellucian.com

CONFIDENTIALITY: This email (including any attachments) may contain confidential, proprietary and privileged information, and unauthorized disclosure or use is prohibited. If you received this email in error, please notify the sender and delete this email from your system. Thank you.

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of Melanie Polutta via groups.io
Sent: Wednesday, July 29, 2020 10:05 AM
To: main@dita-users.groups.io
Subject: [EXT]: [dita-users] Visualizing reltables

 

**External Email**

I am a new user of DITA, and am learning all that it is capable of. In relation to that, I've been looking at reltables, but I am having a hard time visualizing the different ways it can display. Can anyone link up to examples of different ways that reltables can display in a website based on DITA? Or if it isn't publicly accessible, are some screenshots possible? I would really like to understand their capabilities, because I think this markup offers some really useful potential, but I really need help visualizing.


Chris Papademetrious
 

Hi Mona,

Thanks for passing this along! I will share it with my team. We're just starting to look into relationship tables.

 - Chris


 

You welcome Chris, We use Oxygen and publish to our Documentation site hosted by Zoomin Docs.  So some of the instructions are a bit specific to that tool stack, but the visuals and examples of each relationship table link type is basic link structure.

 

Mona Ross | Principal Information Architect | Ellucian® | M:+1.304.596.3712 | www.ellucian.com

CONFIDENTIALITY: This email (including any attachments) may contain confidential, proprietary and privileged information, and unauthorized disclosure or use is prohibited. If you received this email in error, please notify the sender and delete this email from your system. Thank you.

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of Chris Papademetrious via groups.io
Sent: Wednesday, July 29, 2020 4:35 PM
To: main@dita-users.groups.io
Subject: Re: [EXT]: [dita-users] Visualizing reltables

 

**External Email**

Hi Mona,

Thanks for passing this along! I will share it with my team. We're just starting to look into relationship tables.

 - Chris


Wayne Brissette
 

Mona:

This is very, very nice!

I do think though that if we're really honest one of the statements in this document isn't entirely accurate.
The relationship table frees the topics from imbedded links making topics more reusable and aids maintenance of links.
You've stated the party line here. But for those of us who have done this for a long time will tell you all we've done is moved the headache of link maintenance from the topic to the map level. Have we freed the topic? Yes, but we've not really created an easier way to maintain the links. I liken it to sweeping the dirt under the rug. Does the room look clean? Yes, but we've just moved it somewhere else. Reltables in that way too.

In fact, after years of internal debates, we've decided it's no easier to maintain reltables vs. sticking a link in a topic itself. As long as you use keys wisely, in some cases it can be easier to have the link in the topic. Now, that's not always the case, but as is often the case in DITA, there's no one size fits all.

-Wayne


jang
 

I guess it is time for the Geek Philosopher to chime in here… :-)

I agree with Wayne that relationship tables do not really reduce the workload of associating topics and helping customers to find other relevant information. But adding links into topics does not reduce that workload, either. In fact, as long as we still feel the urge to point to other relevant information, we keep hanging on to an old paradigm in a world where documentation meant a manual, tech writers were the experts and a large part of support was meant to be education.

Just ask yourself in all honesty whether you often - if ever - click a link titled ‘further reading’ or ‘relevant information’. I hardly ever do, as I simply do not want to invest the time to read more than I need to know. I have things to achieve, and the only reason I consult any help media is to get a quick and clear answer. If the topic cannot give me that, it may be the case that the information was not mapped out well enough into clearly answerable questions and topic types. Most of all, the metadata that makes it findable at the right time by the right person was probably not defined well enough.

Since the very first time I started using DITA, I have been searching for a way to drive it forward as much as I possibly can. Design the future of technical information, not re-create the past with slightly more modern tools. As far back as 2013, I have delivered a presentation titled ‘Driving DITA Off the Map’ - proposing a software layer that would link topics together based on topic metadata, search terms, a history of user actions etc. In 2015, I followed up with a presentation titled Out of Control - a New Paradigm for Content Management’. In this I developed my vision further and I depicted topics as little animals that would be kicked out into the world - alone, with no friends, no links to relevant information. Those links would appear automagically through usage data (which is basically how all of the internet works today).

I dont see why we need maps, relationship tables, branch filtering and even version control, other than in the old paradigm of the documentation department being in complete control of what is being handed to the clients. Even in such cases, clients do not read your stuff cover to cover: those days have long passed and good riddance to them. We need to move forward and ditch the old habits. We are devoting way too much time to defining the totality of information the users need from us. That is simply fighting a lost battle. We could be having much more success, and much more fun, when devoting all our attention to making our content as dynamic and alive as we possibly can.

Just my 2 cents.

4everJang

Smart Information Design
Amsterdam, Netherlands
Cell: +31 646 854 996

On 30 Jul 2020, 16:11 +0200, Wayne Brissette <wbrisett@...>, wrote:
Mona:

This is very, very nice!

I do think though that if we're really honest one of the statements in
this document isn't entirely accurate.
The relationship table frees the topics from imbedded links making
topics more reusable and aids maintenance of links.
You've stated the party line here. But for those of us who have done
this for a long time will tell you all we've done is moved the headache
of link maintenance from the topic to the map level. Have we freed the
topic? Yes, but we've not really created an easier way to maintain the
links. I liken it to sweeping the dirt under the rug. Does the room look
clean? Yes, but we've just moved it somewhere else. Reltables in that
way too.

In fact, after years of internal debates, we've decided it's no easier
to maintain reltables vs. sticking a link in a topic itself. As long as
you use keys wisely, in some cases it can be easier to have the link in
the topic. Now, that's not always the case, but as is often the case in
DITA, there's no one size fits all.

-Wayne




Julio J Vazquez
 

Keep in mind that different processors or customizations can result in different looks. Also,  you can control the way the linking works.  The basic result is that at the end of the topics there are links to the targets with the ability to control the titles in each rel column in the relheader.

Julio J. Vazquez


 

I couldn’t agree more. 

 

However, as content is being migrated from old PDF book paradigm to new task-based html micro content, we have to deal with what to do with the abusive use of cross document linking in the old source.  Most of the links we blow away, however, there are many that have to remain due to keeping the “big picture” intact.

 

Some companies have to support customers on any number of versions and have complex application setups with hundreds of complex steps described in entire chapters.  Writers still have to connect the big picture these legacy PDF monstrosities describe until they can perform a full analysis and re-write to apply minimalism.  Not all companies have the downtime and band-width to do that.  So there still is a need at least for some time period, to manage cross document, topic linking.

 

DITA Best Practices stated that Relationship tables are a better practice than inline cross-references as in-line cross references can easily break if you don’t have a CCMS to manage the source and target to avoid broken links.

 

Mona Ross | Principal Information Architect | Ellucian® | M:+1.304.596.3712 | www.ellucian.com

CONFIDENTIALITY: This email (including any attachments) may contain confidential, proprietary and privileged information, and unauthorized disclosure or use is prohibited. If you received this email in error, please notify the sender and delete this email from your system. Thank you.

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of jang via groups.io
Sent: Thursday, July 30, 2020 12:08 PM
To: main@dita-users.groups.io
Subject: Re: [EXT]: [dita-users] Visualizing reltables

 

**External Email**

I guess it is time for the Geek Philosopher to chime in here… :-)

I agree with Wayne that relationship tables do not really reduce the workload of associating topics and helping customers to find other relevant information. But adding links into topics does not reduce that workload, either. In fact, as long as we still feel the urge to point to other relevant information, we keep hanging on to an old paradigm in a world where documentation meant a manual, tech writers were the experts and a large part of support was meant to be education.

Just ask yourself in all honesty whether you often - if ever - click a link titled ‘further reading’ or ‘relevant information’. I hardly ever do, as I simply do not want to invest the time to read more than I need to know. I have things to achieve, and the only reason I consult any help media is to get a quick and clear answer. If the topic cannot give me that, it may be the case that the information was not mapped out well enough into clearly answerable questions and topic types. Most of all, the metadata that makes it findable at the right time by the right person was probably not defined well enough.

Since the very first time I started using DITA, I have been searching for a way to drive it forward as much as I possibly can. Design the future of technical information, not re-create the past with slightly more modern tools. As far back as 2013, I have delivered a presentation titled ‘Driving DITA Off the Map’ - proposing a software layer that would link topics together based on topic metadata, search terms, a history of user actions etc. In 2015, I followed up with a presentation titled ‘Out of Control - a New Paradigm for Content Management’. In this I developed my vision further and I depicted topics as little animals that would be kicked out into the world - alone, with no friends, no links to ‘relevant information’. Those links would appear automagically through usage data (which is basically how all of the internet works today).

I don’t see why we need maps, relationship tables, branch filtering and even version control, other than in the old paradigm of the documentation department being in complete control of what is being handed to the clients. Even in such cases, clients do not read your stuff cover to cover: those days have long passed and good riddance to them. We need to move forward and ditch the old habits. We are devoting way too much time to defining the totality of information the users need from us. That is simply fighting a lost battle. We could be having much more success, and much more fun, when devoting all our attention to making our content as dynamic and alive as we possibly can.

Just my 2 cents.

4everJang


Smart Information Design

Amsterdam, Netherlands

Cell: +31 646 854 996

On 30 Jul 2020, 16:11 +0200, Wayne Brissette <wbrisett@...>, wrote:

Mona:

This is very, very nice!

I do think though that if we're really honest one of the statements in
this document isn't entirely accurate.

The relationship table frees the topics from imbedded links making
topics more reusable and aids maintenance of links.

You've stated the party line here. But for those of us who have done
this for a long time will tell you all we've done is moved the headache
of link maintenance from the topic to the map level. Have we freed the
topic? Yes, but we've not really created an easier way to maintain the
links. I liken it to sweeping the dirt under the rug. Does the room look
clean? Yes, but we've just moved it somewhere else. Reltables in that
way too.

In fact, after years of internal debates, we've decided it's no easier
to maintain reltables vs. sticking a link in a topic itself. As long as
you use keys wisely, in some cases it can be easier to have the link in
the topic. Now, that's not always the case, but as is often the case in
DITA, there's no one size fits all.

-Wayne



Melanie Polutta
 

Well, I didn't intend to start a philosophical discussion. But I would actually dispute some of the statements made above, even without much experience in producing DITA content. (I'm new to it.) Speaking as a consumer, I find many of the websites that present information to me without a coherent narrative of instructions very confusing to figure out. Yes, I may jump around, but I do so within that context, which assists me to make decisions.

For the technical information I'm producing, my users are very accustomed to that TOC-dictated narrative flow of instructions. They use that to navigate and find things. A decentralized search capability as the sole means of finding information is not welcome to them, and has already been greatly criticized. So I am very interested in providing some kind of TOC replacement, and was wondering if the reltables function might assist in that. (I'm also looking at ditamaps for a different way to organize the decentralized information.)

Truth be told, I don't think those kinds of sweeping statements are always correct, because it depends on the kind of tech instruction you are giving and the context it works in. Metadata has limits. (If you're curious, I am dealing with cataloging standards in the library world. So I am perhaps more aware than most of the capabilities and limitations of metadata, because I work with it every day.)


Wayne Brissette
 

Melanie Polutta wrote on 2020-07-30 19:35:
Well, I didn't intend to start a philosophical discussion.
I don't think you did. What you discovered though is DITA is different to everybody. That is the beauty behind it. For some people and companies, it's an alternative authoring system. For others, it's a way to provide information that their customers need, using things other than traditional publication systems. And therein lies the 'magic' of XML and DITA. We're doing a lot more automation so we aren't using DITA as the source of truth anymore. Instead we use it as the common platform that allows us to publish, validate, and ensure we provide exactly what is expected to our customers. Since we're not using DITA strictly as an authoring platform, the rules about what is considered 'best practice' is slightly different to us. Jang takes this way beyond where we currently feel comfortable, but he's not wrong. Nor are those who are using DITA as an authoring platform to simply replace traditional tools like Word and FrameMaker in the Tech Comm space. We all have varied needs and those needs change as the industry moves forward and as the types of information we deliver changes.

-Wayne


jang
 

I take Wayne’s side remark - about me taking things way beyond what most people feel comfortable with - as a compliment. And I need to add that I am not against using maps (or even relationship tables) - I just want to find a way in which these maps can be auto-generated on-the-fly based on decent topic metadata matched to the user’s situation, preferences and search history.

Relationships between topics are NOT part of the topic metadata, but they should not exist outside of the topics either - they should be derived from the collection of topic metadata (which possibly and even preferably includes the outcome of text analysis tools and other techniques such as click traces, etc.). I would want to create something that works like Google, but better (and not infected with commercial interests). And I truly believe that there are no hand-crafted maps or relationship tables anywhere to be found in that company.

+2 cents - that makes 4 already !!

Jang

Smart Information Design
Amsterdam, Netherlands
Cell: +31 646 854 996

On 31 Jul 2020, 14:41 +0200, Wayne Brissette <wbrisett@...>, wrote:


Melanie Polutta wrote on 2020-07-30 19:35:
Well, I didn't intend to start a philosophical discussion.
I don't think you did. What you discovered though is DITA is different
to everybody. That is the beauty behind it. For some people and
companies, it's an alternative authoring system. For others, it's a way
to provide information that their customers need, using things other
than traditional publication systems. And therein lies the 'magic' of
XML and DITA. We're doing a lot more automation so we aren't using DITA
as the source of truth anymore. Instead we use it as the common platform
that allows us to publish, validate, and ensure we provide exactly what
is expected to our customers. Since we're not using DITA strictly as an
authoring platform, the rules about what is considered 'best practice'
is slightly different to us. Jang takes this way beyond where we
currently feel comfortable, but he's not wrong. Nor are those who are
using DITA as an authoring platform to simply replace traditional tools
like Word and FrameMaker in the Tech Comm space. We all have varied
needs and those needs change as the industry moves forward and as the
types of information we deliver changes.

-Wayne




Joe Pairman
 

Well said, Wayne. Organizations use DITA in all sorts of ways for different situations.

Back on reltables specifically, I wanted to echo your earlier point that reltables do not eliminate the issues around maintaining links. They do consolidate those issues into fewer objects though, which can help.

In terms of visualizing structure, I really like the clear document that Mona shared. I would also point out though that you do not necessarily need to keep the task - concept - reference structure in your reltables, with their reciprocal links and default output. If you are info typing your topics in a different way, or if info type groups are not so relevant to display in the generated links, you can use a different structure.

Something that worked well for an implementation I did in the past was to have two columns only: source and target (there is an attribute to set on the columns to make the links behave this way). Then it is extremely clear for authors what topic links to what other one, and how.

(As to my personal preferences for links, I do feel there are cases where you need a good old hypertext type of approach: an inline link pointing to a clearly described target and saying why it's linking there. Very manual, though you can streamline and safeguard the process a bit. But high value for cases where a topic to topic link, or a purely metadata-generated one, would not be precise enough. I have done metadata-based fully automated links too and they can be great. But sometimes you can't beat a clearly labelled inline link).

On Fri, Jul 31, 2020 at 1:41 PM Wayne Brissette <wbrisett@...> wrote:


Melanie Polutta wrote on 2020-07-30 19:35:
> Well, I didn't intend to start a philosophical discussion.
I don't think you did. What you discovered though is DITA is different
to everybody. That is the beauty behind it. For some people and
companies, it's an alternative authoring system. For others, it's a way
to provide information that their customers need, using things other
than traditional publication systems. And therein lies the 'magic' of
XML and DITA. We're doing a lot more automation so we aren't using DITA
as the source of truth anymore. Instead we use it as the common platform
that allows us to publish, validate, and ensure we provide exactly what
is expected to our customers. Since we're not using DITA strictly as an
authoring platform, the rules about what is considered 'best practice'
is slightly different to us. Jang takes this way beyond where we
currently feel comfortable, but he's not wrong. Nor are those who are
using DITA as an authoring platform to simply replace traditional tools
like Word and FrameMaker in the Tech Comm space. We all have varied
needs and those needs change as the industry moves forward and as the
types of information we deliver changes.

-Wayne




Lief Erickson
 

This reminds me of a project that Mark Baker started several years ago. His SPFE project never took off, but his thinking on soft linking and how to build them seem relevant to this conversation. A quick search will get interested people to his posts. 


On Fri, Jul 31, 2020 at 8:02 AM jang <jang@...> wrote:
Relationships between topics are NOT part of the topic metadata, but they should not exist outside of the topics either - they should be derived from the collection of topic metadata (which possibly and even preferably includes the outcome of text analysis tools and other techniques such as click traces, etc.). I would want to create something that works like Google, but better (and not infected with commercial interests). And I truly believe that there are no hand-crafted maps or relationship tables anywhere to be found in that company.