Best practices for documenting DITA map changes and revisions involve using clear version control commit messages, change logs, and issue tracking systems to maintain a comprehensive history of modifications.

Documenting DITA map changes and revisions is crucial for tracking the evolution of content. This involves clear commit messages, change logs, issue tracking, and collaborative tools.

Clear Commit Messages

When authors make changes to a DITA map, they should provide clear and descriptive commit messages in the version control system. These messages should summarize what was changed, why the change was made, and any relevant context.

Change Logs

Maintain change logs that track when and by whom changes were made. Change logs can include details like the date of the change, the author, the type of change (e.g., correction, addition, deletion), and any associated issue or task numbers.

Issue Tracking

Link DITA map changes to issue or task tracking systems. When an author identifies an issue in the content, they can create a corresponding issue in the tracking system. Changes made to address the issue can reference the issue number in the commit message. This provides a direct link between changes and the reasons behind them.

Collaborative Tools

Use collaborative authoring tools that automatically capture changes and allow authors to add comments or annotations explaining the purpose of a change.

Example

In a DITA map development project, an author is revising a map to include new product features. When committing the changes to the version control system, they write a clear commit message, “Updated DITA map to include new product features – Issue #123.” The issue number, #123, corresponds to a task in the issue tracking system that details the requirement for these changes. In the issue tracking system, there is a comprehensive record of the issue, including its description, status, and associated changes. By documenting changes this way, the author and the team have a clear history of the map’s revisions and the reasons behind each modification, aiding in content transparency and collaboration.