Conref and keyref best practices
IXIASOFT CCMS provides a topic specialization and a map template that let you store and organize your reusable components.
You use the referable-content topic type to hold the text that you plan to reuse in other topics. You then build libraries of referable-content topics using a referable_component_library map.
When creating reusable components and maps, IXIASOFT recommends that you follow these best practices.
About reusable components
- Always use the referable-content topic type to store your reusable components. Otherwise, they will not be searchable with the Referable-Content view.
- Ideally, keep each reusable component as small as possible and store them in a separate referable-content topic. While this is not mandatory, it allows for a better organization of the reusable components and will have less impact on your work flow. For example, if you plan to reuse error messages, keep each error message in its own topic. This ensures that if you need to update a single message, only the topics that refer to this message will be impacted in your work flow (as opposed to storing all messages in a single topic, which would cause all the objects that reference any error message in the topic to be impacted).
- Assign IDs to each referable piece of content. IDs should follow a pre-defined naming convention for ease of use and standardization. You can also use the IDs that are automatically generated when you release the referable-content topic. See the Administration Guide for the CCMS for more information about configuring the CCMS to automatically generate IDs.
- Label your reusable components so that you can also find them using the Advanced Search.
About reusable maps
- Organize your referable-content topics in a referable_component_library map.
- Maps are the key to organizing your reusable components so that
you can find them easily. Determine a strategy for organizing your maps; for
example, you could organize your maps:
- By logical group: Create a map for error messages, a map for warnings, a map for labels, etc.
- By product: Create a map for product A, a map for product B, etc.
- You could also build a map from all reusable objects that share the same label.
About keys
Several ways are available for adding keys to maps; however, you may want to establish a list of variables for use by the entire team rather than have each user define their own. To provide this list of common or corporately-approved variables, the Administrator can configure a list in the Content Store which can be made available for selection in the DITA Map view.