How to optimize DITA map structure for large projects with many cross-linked topics?

[lylybr]

Hi everyone,
I am working on a fairly large DITA project, consisting of hundreds of topics spread across many different modules, including many cross-links between topics. Currently, my DITA Map is starting to become confusing and difficult to manage when publishing to many outputs (HTML5, PDF).
I would like to ask:

• Is there any way to organize or split the DITA map to make it easier to manage?

• How should I use submaps and keyrefs to both maintain a clear structure and limit linking errors?

• Are there any best practices for naming files/topics for convenience in long-term maintenance?

I hope to learn from those who have handled large-scale DITA projects.
Thank you, everyone!

[Radu]

Hi,
The Oxygen forum is a place where people in general register to receive answers to their own questions, so there may not be many DITA writers registered to receive answers on any post. I would suggest you also join the DITA Users List and ask the community: https://dita-users.groups.io/g/main

Coming back to your question, as an example we have the Oxygen User's Manual DITA XML content stored on GitHub, it's not a perfect project but it's scalable and it works:
https://github.com/oxygenxml/userguide/tree/master/DITA

We have a top level "UserManual.ditamap" and then for each individual chapter we have a submap which we store in the "maps" folder.
There is a keydefs.ditamap which stores key definitions for various variables used throughout the entire user's manual:
https://github.com/oxygenxml/userguide/ ... fs.ditamap
And there is a reusables.ditamap which defines keys pointing to reusable content topics:
https://github.com/oxygenxml/userguide/ ... es.ditamap

We use profiling attributes to generate from the same top level DITA Map about 10-15 different publications using ditaval filter files (https://github.com/oxygenxml/userguide/ ... TA/ditaval).
We use keyrefs for frequently mentioned product names like "Oxygen XML Editor", use use conkeyrefs for reusing DITA XML elements like notes, tables. We still use direct links between topics, so we do not use keyrefs or relationship tables defined at DITA Map level.

There are various settings stored at project level, so if one loads the "userguide.xpr" project in the Oxygen Project view they get various settings imposed, for example custom Schematron validation rules, spell check rules and learned words list.
Also the project has the "Main Files" feature in Oxygen enabled with the main Userguide ditamap added as a main file, making Oxygen automatically fix up references when one renames or moves resources in the Project view.

Some more details can be found in these sample projects:

https://github.com/oxygenxml/DITA-Startup-Project
https://github.com/oxygenxml/dita-proje ... -practices

Regards,
Radu