Gar, making changes to ServiceNow reuse topics would be a ridiculous expenditure! And again, I think ever company is going to do things slightly differently, based on many different factors:
- What content repository they use
- What DITA information architecture was initially in use
- Company culture
- Working habits of folks authoring content
There clearly in NO one way to store the elements targeted by @conref or @conkeyref. But if all the examples in the DITA spec assumes a particular model, then we kind of implying that there is one preferred way.
So, what do we do with the conref examples in the spec? Vary them? Make an explicit statement that there are many different approaches to store elements targeted by @conref and @conkeyref? Other thoughts?
Kris
------------------------------
Kristen Eberlein
Eberlein Consulting LLC
Durham NC
919-622-1501
------------------------------
Original Message:
Sent: 09-23-2024 10:26
From: Eliot Kimber
Subject: Warehouse (library) topics vs reusable component topics
I think it largely depends on how the reusable components are managed and by whom-the example I always use is a topic containing admonitions that go through their own legal approval workflow-it makes sense to have them in a single topic for ease of access and management. But it would just as well to have one admonition per topic and then a dedicated map that organizes just those topics for review and approval.
So I see the appeal of having one reusable element per topic, especially in a CCMS or key-based environment, where the topic's key(s) essentially become synonymous with the element's ID.
Here at ServiceNow we have lots of warehouse topics used within and among dozens of publications managed in git without any kind of CCMS and for the most part it seems to work fine-the files do not change that often and the organization of the elements into topics seems to make sense to authors (at least to point it's not worth the effort of changing them). Oxygen's reusable component features make it easy enough to find things and, because we use keys, validation of dependencies is reliable and relatively easy to correct.
So for us, I'd be hard pressed to justify a change to one element per topic-it would add many 1000s of topics to no obvious benefit. But we also have pretty complete infrastructure for processing our content, for example, being able to do map resolution in Oxygen refactors in order to find and operate on all content key references in a publication (or across publications).
Cheers,
E.
_____________________________________________
Eliot Kimber
Sr. Staff Content Engineer
O: 512 554 9368
servicenow
servicenow.com
LinkedIn | X | YouTube | Instagram
Original Message:
Sent: 9/21/2024 3:57:00 PM
From: Kristen Eberlein
Subject: Warehouse (library) topics vs reusable component topics
Folks, I've been reading through the conref content that is currently under review. When I came to the example, I see that they tend to be written based on the assumption that folks will be using warehouse (library) topics. I'd define a warehouse topic as a DITA topic that contains many different elements intended for reuse.
I know that over the last decade or so, I started suggesting that clients use "reusable component topics" instead of large library files. I'd define a "reusable component topic" as a DITA topic that contains a single element intended for reuse. Why? Largely to mitigate against large scale dependencies and document-state changes in a CCMS.
Thoughts and practices from others?
Kris
------------------------------
Kristen Eberlein
Eberlein Consulting LLC
Durham NC
919-622-1501
------------------------------