• 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

  • My input here is to broathen the horizon on this thread. Technically I think a tool can be written based on the API, but a generic tool might not be that easy as everybody's starting situation regarding information architecture on conref usage is different.

    For those of you who didn't start yet, I would like to point out that the Knowledge Center Content Manager has an alternative called 'Variables'.

    • With the OASIS DITA @conref structure, you have to specify something like A/B#C as conref value assisted by the tools. Now in the CMS the A and B-part are usually the same unless you start using advanced nesting structures. The C-part is your identifier in the library identified by A.
    • Variables only have the C-part in the referencing system we have before OASIS DITA was there. So in one topic you use the variable reference (@varref) and in another library file you resolve the variable (@varid).

    As @conref structure are more rigid on the A-part, the @varref structure is wide open. Tools like Publication Manager will tell you if you try to resolve a variable usage with more than one assignment, which in theory could from different library files.

    As a best practice I once picked up in a user group is to organize your variable assignment libraries by

    1. company like copyright year, company name
    2. product level like name
    3. per publication

    It was also mentioned that variables are easier for localization than conrefs. I also remember a statement: "A condition on a conref is probably a variable".

    My 2 cents
    Dave
Reply

  • My input here is to broathen the horizon on this thread. Technically I think a tool can be written based on the API, but a generic tool might not be that easy as everybody's starting situation regarding information architecture on conref usage is different.

    For those of you who didn't start yet, I would like to point out that the Knowledge Center Content Manager has an alternative called 'Variables'.

    • With the OASIS DITA @conref structure, you have to specify something like A/B#C as conref value assisted by the tools. Now in the CMS the A and B-part are usually the same unless you start using advanced nesting structures. The C-part is your identifier in the library identified by A.
    • Variables only have the C-part in the referencing system we have before OASIS DITA was there. So in one topic you use the variable reference (@varref) and in another library file you resolve the variable (@varid).

    As @conref structure are more rigid on the A-part, the @varref structure is wide open. Tools like Publication Manager will tell you if you try to resolve a variable usage with more than one assignment, which in theory could from different library files.

    As a best practice I once picked up in a user group is to organize your variable assignment libraries by

    1. company like copyright year, company name
    2. product level like name
    3. per publication

    It was also mentioned that variables are easier for localization than conrefs. I also remember a statement: "A condition on a conref is probably a variable".

    My 2 cents
    Dave
Children
  • in reply to Dave De Meyer
    Hi Dave,
    Those are good points. Essentially I guess I see variables and conrefs as two rather different concepts, though. Conref could replace variables in principle, but not the other way around.

    I mean, variables are used to manage simple textual and numerical values or graphics. For the use cases in your list they are perfect and a much better idea than conrefs. But I suspect variables would not cut it in Mathijs' use case, where bigger chunks of markup is referenced (and also validated at the insertion point of course).

    Indirect addressing is always a good idea, so use @conkeyref instead of @conref.

    Ps. I have never tried what would happen if a variable resolved to markup - I guess it would just show as a string of text? Not that it is relevant to the questions in this thread...