Best Practices for Reusing DITA Topics Across Multiple Publications

[uitoeshrill]

Hi everyone,

I’m working on a project where I need to reuse the same DITA topics across several different publications with slightly different contexts (for example, a user guide, an installation manual, and a quick start guide). I’m a bit unsure about the cleanest approach for managing this in OxygenXML without duplicating content unnecessarily.

Should I rely more on conref and keyref mechanisms, or is it better to structure the maps differently depending on the publication? Also, how do you usually handle conditional content when one publication needs more technical detail than another?

I’d love to hear your strategies or workflows for keeping reused content consistent and easy to maintain. Any examples or tips would be really helpful!

Thanks in advance!

[Radu]

Hi,

Most users on the Oxygen forum are registered to receive replies only on their threads. If you want feedback from a wide range of DITA users you could consider registering on the DITA Users List and asking the question also there.
https://dita-users.groups.io/g/main

About your question, let's say I have a topic which I want to reuse in multiple publications.
I can produce multiple publications from a single DITA Map (with DITAVAL filter files) or from multiple maps. If a lot of topics and table of contents is shared between publications, you could have a single DITA Map with ditaval filters, otherwise it's cleaner to have multiple top level maps.
If the topic has variable content inside it, it can use key references to refer to product names which have distinct values in each DITA Map or it can use profiling attributes on certain elements to show or filter them depending on the DITAVAL filters applied on each map, or it can use conkeyref's to refer to certain reusable elements and the keys being defined with different targets in each publication DITA Map.

In our case for the Oxygen user's manual we have a top level "UserManual.ditamap" and lots of filters. We produce about 19 distinct publications by applying each ditaval filter on the DITA Map.

https://github.com/oxygenxml/userguide/ ... al.ditamap
https://github.com/oxygenxml/userguide/ ... TA/ditaval

At the same time, I wanted to produce a separate publication for add-ons and because it had a totally different TOC I decided to create a separate top level map for it and reuse topics from the "topics/" folder:

https://github.com/oxygenxml/userguide/ ... ns.ditamap

So whatever suits better in your context...

Regards,
Radu