Re: <resourceid> element's @appid attribute


ekimber@contrext.com
 

Radu's approach works *as long as* topic IDs and/or filenames are unique across your corpus of topics. There is nothing in the DITA standard that requires either of those two conditions to be true.

Because I'm that guy, I make a point of making every topic ID "topicid" when I can to ensure that systems and processors that assume topic IDs are always unique will break. Likewise, in a given corpus, you might have many topics with a filename of "introduction.dita" or something [Full disclosure: I built a DITA import process for a product I used to work on where it broke when filenames were not unique--that was particularly painful because I discovered the breakage when I tried to import a set of data I had created: the DITA version of John Bosak's XML Shakespeare's Plays. Hoist on my own petard.].

Of course, the full URI of any given topic is unique, so using a hash of the URI would always produce a unique value but that's not very human friendly.

The most general solution would be to either use <resourceid> within topics to assign unique names within some appropriate scope (might be your full corpus, might be just for a given product's documentation, or a library of products, or whatever) or to use keys as the basis of deliverable anchors.

Putting <resourceid> in topics where you ensure the <resourceid> values are appropriately unique makes the topics independently globally named (that is, you aren't relying on keys defined in maps to get name uniqueness). It serves the same purpose that Radu's ID- or filename-based approach does but doesn't limit your choices for either IDs or filenames, which might have other forces that need to control their values in a way that doesn't necessarily guarantee uniqueness.

I'm starting to see <resourceid> as the best way to manage global identifier uniqueness separate from keys, IDs, or filenames. It has several advantages over using any of the other available identifiers:

* Can have completely independent business rules.
* Can have different rules for different use environments (different deliverables, different tools, different business rules)
* Can have multiple resource IDs for the same resource
* Topics can assert their own resource IDs (topics cannot assert their own keys using DITA-defined mechanisms)

If you consider the use case of needing to migrate your content to a new organizational strategy or a new storage model, that likely means a change to some or all filenames or a change to your key naming strategy or some other potentially disruptive change. Because resource IDs are separate from these, they can be unaffected by this sort of source-level change. You might also decide to change your information architecture approach, which can change how you use keys, requiring a change to key names (or the addition of new keys to reflect the new architecture).

For people just starting out with DITA, it's probably hard to imagine how these name-management concerns are important, but once you've been using DITA for a few years, you will almost certainly be faced with some kind of disruptive change to how your DITA source is stored and managed, or a change to your Information Architecture approach, that requires modifying keys, filenames, or IDs. It will happen.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


´╗┐On 2/14/21, 10:41 PM, "Radu Coravu" <main@dita-users.groups.io on behalf of radu_coravu@sync.ro> wrote:






Hi John,
Our WebHelp feature which generates context ids used to link to
topics looks at both the @id attribute of the topic and at the
"resourceid" element. As topic IDs are required and need to be
specified inside the DITA topic anyway we decided to use the topic
ID as the context id, and added some Schematron rules to insure
that the topic ID always matches the file name, to provide some
kind of uniqueness of the topic ID in the entire DITA project
context.

Regards,
Radu
Radu Coravu
Oxygen XML Editor

On 2/13/21 04:27,
john.kirkilis@nokia.com wrote:



Hi Radu,

In the hopes of finding an example document set, I downloaded the
Oxygen userguide source from GitHub and couldn't find any
instances of <resourceid> being used anywhere in the
content. I thought perhaps that's how you linked to your web help
from Oxygen's help icon in every dialog box.

Regards,

John

Join main@dita-users.groups.io to automatically receive all group messages.