toggle quoted messageShow quoted text
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.
Principal Information Architect
This email (including
use is prohibited.
error, please notify the sender
system. Thank you.
On Behalf Of
jang via groups.io
Thursday, July 30, 2020 12:08 PM
Re: [EXT]: [dita-users] Visualizing reltables
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.
On 30 Jul 2020, 16:11 +0200, Wayne Brissette <wbrisett@...>, wrote:
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
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.