In DITA, when reused topics are moved or deleted, it can impact the consistency and integrity of documentation. Proper strategies for managing these changes are crucial to avoid broken links and maintain content coherence.

Strategies for Managing Changes

These strategies include link management, content updates, change tracking, and firm content reuse strategies.

Link Management:

DITA relies on links to connect topics within documentation. Reused topics are typically referenced in maps or other topics using topicref elements. If a reused topic is moved or deleted, these references can become broken links, leading to inconsistencies in the content.

Content Updates:

When a reused topic is moved or deleted, it’s essential to consider whether the content needs to be updated. If the topic is moved to a new location, the references to it must be updated to reflect the new path. If the topic is deleted, it should either be replaced with a suitable alternative or the referencing topics updated to remove the links.

Change Tracking:

It’s advisable to keep track of changes to reused topics, especially in collaborative authoring environments. Use version control systems or content management tools to ensure that changes are coordinated among team members. This helps prevent unintentional breaks in the documentation.

Content Reuse Strategies:

To mitigate the impact of moved or deleted topics, adopt strategies such as minimal content reuse, encapsulation, and the use of conditional processing. By encapsulating reused content in a dedicated topic, the number of references to it can be limited, making updates and maintenance more manageable.

Example:

A software user manual reuses a common troubleshooting topic across multiple chapters. If the troubleshooting topic is moved to a different section of the documentation, the following actions should be taken:

Update References: Locate all instances where the troubleshooting topic was reused in the DITA map or other topics. Update the topicref elements to point to the new location of the topic.

Review Content: Ensure that the content within the moved topic remains relevant in its new context. The content may need to be updated to fit the new section’s structure or purpose.

Test the Output: Generate output, such as HTML or PDF, to verify that the changes did not introduce issues like broken links or formatting problems. Testing helps ensure the documentation remains coherent and functional.

Coordinate Changes: Communicating the move of the topic to avoid conflicts and ensuring that other team members are aware of the change is extremely important. This way, everyone can adjust their work accordingly.