• Replies 4 replies
  • Subscribers 48 subscribers
  • Views 2073 views
  • Users 0 members are here
Options
Related

Proposal: conref migration tool

Mathijs Panhuijsen

Hi all,

I'd like to ask if people see a point to having a tool that allows you to take elements used as conref targets in one Library Topic, and move them to another Library Topic. Currently, this will break all references to those conref targets, because conref references include the (Library) Topic ID. The migration tool would go through your repository and update all the references.

Use case 1:

I have created one very large Library Topic, containing a large number of reusable steps, reusable strings and so on. I also have a deliverable that uses a small fraction of those steps and strings, and I want to have this deliverable translated. Because the deliverable references my Library Topic, the Library Topic gets sent out for translation as well, and translators spend a lot of time translating content that isn't part of my deliverable.

What I would like to do is take the few reusable steps and strings that are actually used in my deliverable, and split them off, that is, put them in their own Library Topic. However, if I just copy-paste the steps and strings into a new Library Topic, all my references to those steps and strings are broken, and I have to spend a lot of time fixing them by hand.

Use case 2:

I have documentation for a software product that consists of three software components, let's call them Foo, Bar and Fred. My Library Topic contains reusable steps related to all three software components. Now, the Fred software component gets repurposed and used by a completely different software product. The docs for this other product need to reference some steps in my Library Topic, but only steps pertaining to Fred.

Here, too, I want to separate off some of the steps in my Library Topic and put them in a separate, new Library Topic. And again, doing so, would break tons of references.

In both use cases, you could argue that I should have organized my Library Topics more "finely," not mixing translatable content with non-translatable content, or not mixing Foo, Bar and Fred content. But it's often hard to predict where and how pieces of content are going to be used.

The problem that arises is one that is almost impossible to fix by hand, but would be very easy to build as a product feature.
Rate translation
×
Suggest better translation
×
Parents

  • Hi.

    Define "very easy"...

    Interesting idea. So, suppose you wanted to make this kind of change, would it be forward-looking only or should the references really be updated throughout the database, that is, including released content in all languages? Those two are rather different propositions to start with. I think I would steer clear of the latter option.

    I guess my first reaction would be to limit the functionality so that any changes would be made to draft content. Meaning for any references found in released content, a new version would be (automagically) created and the conref references updated there. And probably an XML comment to flag the change made with a timestamp. The changes would trickle down to translations as any other changes, over time.

    Definitely the functionality should also generate a detailed report of:

    • new objects created
    • objects modified (those which were already in draft state)

    Finding the conrefs and modifying them is not per se a problem in principle. Those could be mined from metadata, FISHFRAGMENTLINKS and FISHLINKS fields.

    I sense a lot of edge cases in the wings, this would have to carefully analyzed.

    Alternatively, at least as as first step you could generate a report of the object/version/language that have the conref reference you wish to change. Then that would give an idea of the workload.

    Just some thoughts.

    Joakim
Reply

  • Hi.

    Define "very easy"...

    Interesting idea. So, suppose you wanted to make this kind of change, would it be forward-looking only or should the references really be updated throughout the database, that is, including released content in all languages? Those two are rather different propositions to start with. I think I would steer clear of the latter option.

    I guess my first reaction would be to limit the functionality so that any changes would be made to draft content. Meaning for any references found in released content, a new version would be (automagically) created and the conref references updated there. And probably an XML comment to flag the change made with a timestamp. The changes would trickle down to translations as any other changes, over time.

    Definitely the functionality should also generate a detailed report of:

    • new objects created
    • objects modified (those which were already in draft state)

    Finding the conrefs and modifying them is not per se a problem in principle. Those could be mined from metadata, FISHFRAGMENTLINKS and FISHLINKS fields.

    I sense a lot of edge cases in the wings, this would have to carefully analyzed.

    Alternatively, at least as as first step you could generate a report of the object/version/language that have the conref reference you wish to change. Then that would give an idea of the workload.

    Just some thoughts.

    Joakim
Children
  • in reply to Joakim Nybäck
    All good points. The problem is more complicated than I at first imagined. I would agree with taking a forward-thinking approach, that is, from this point forward, update all the references in draft content only.

    The best approach would then be to make a clean break, that is, not to remove some items from the old LT, but to completely abandon the old LT in favor of two (or more) new LTs. That would also make it clearer for any topic whether it's old-style or new-style.

    I also agree that a report-generating plugin would be a great first step. It's hard to quantify the effort involved in a manual task without such a tool. I guess you could very primitively get an impression by doing the following:

    1. Identify the GUIDs of the reusable content elements you would want to split off.
    2. Search for those GUIDs in Browse Repository in Publication Manager and count up the number of hits you get.

    Depending on how many items you want to split off, this could take you several hours, but at the end you'd have a rough idea of the work that would be involved.