Is there a downside to having too many circular references?

When we open a publication in Pub Manager, we see a lot of error messages about circular references. These are occasioned by the following scenario:
1. Topic A has a conref to an element in Topic B
2. Topic B has a conref to an element in Topic A

Because this scenario is valid DITA, I learned to ignore the messages. But I'd like to know if there's a downside. Recently, Pub Manager started crashing when we tried to open a pub with a lot of these cross-references. I think we isolated the cause to something else, but it left me wondering. Does anyone know if there's an adverse affect to having too many of these circular references? For example, does it slow down Tridion Docs or cause other processing issues?

emoji
Parents
  • Although it is possible to conref from one topic to another, and create circular references, doing a lot of it can result in "spaghetti code."  This spaghetti code can at some point down the road, prevent you from being able to release a publication, because something in that publication depends on some other thing being in a released state, but that thing can't be released because it conrefs something that isn't released, and so on. Eventually, someone will want to change an item that is conref'd.  Then what?  How will they know what will be affected by that change?  How to they know it's been conref'd?

    So, when you have a small number of items to keep track of, you might be able to manage it, but once you start scaling up and getting multiple writers, the complexity gets you.

    There are some existing posts out there that discuss best practices for reuse, which suggest keeping a set of source topics in a particular part of the repository, and only conref from those specific topics.  For example, you might have a topic full of common alerts, and all your other topics grab the alerts from those topics. See  DITA Best Practices (Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt), and for a quick illustration of what I'm talking about, see https://www.ditawriter.com/specializing-conref-target-topics-to-avoid-spaghetti-code/

    emoji
Reply
  • Although it is possible to conref from one topic to another, and create circular references, doing a lot of it can result in "spaghetti code."  This spaghetti code can at some point down the road, prevent you from being able to release a publication, because something in that publication depends on some other thing being in a released state, but that thing can't be released because it conrefs something that isn't released, and so on. Eventually, someone will want to change an item that is conref'd.  Then what?  How will they know what will be affected by that change?  How to they know it's been conref'd?

    So, when you have a small number of items to keep track of, you might be able to manage it, but once you start scaling up and getting multiple writers, the complexity gets you.

    There are some existing posts out there that discuss best practices for reuse, which suggest keeping a set of source topics in a particular part of the repository, and only conref from those specific topics.  For example, you might have a topic full of common alerts, and all your other topics grab the alerts from those topics. See  DITA Best Practices (Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt), and for a quick illustration of what I'm talking about, see https://www.ditawriter.com/specializing-conref-target-topics-to-avoid-spaghetti-code/

    emoji
Children
  • Thank you, Trish. I agree completely: What you've described are the best practices for reuse in DITA.

    In my case, Topic A is (for example) the enable macsec command description, Topic B is the disable macsec command description, and they reference each other. No spaghetti. However, as you point out, the potential for mischief is increased, for example if a writer edited one of the topics and added a reference to an object that was outside the publication.

    emoji
  • Great discussion! Thanks for starting it, Larry, and thanks to Trish for describing the general best practice in DITA (helpful to a wider audience).

    One of the great things around having tools to shape on top of the standard, is that you can reinforce best practices and somewhat discourage practices that could get the unwary into trouble. So we do recommend that customers exclusively use library topic types as sources for conrefs. And hence the warning message (more of a nudge I hope than a blaring klaxon!)

    Larry, in this case would it work to house the common passage that's reused between those topics in a dedicated library topic? I know there are always exceptions but that is the "by the book" recommendation here I'd say.

    P.S. – you don't have to but I always used to get the writing team adding the library topics to the Resources "folder" at the bottom of the publication, as a clear, quick place to see not only variable sources but conref sources too.

    emoji