Good practices with multiple versions and ditavals

Post here questions and problems related to editing and publishing DITA content.
gbv34
Posts: 105
Joined: Thu Jan 20, 2022 12:36 pm

Good practices with multiple versions and ditavals

Post by gbv34 »

Hello,
I have a documentation that is regularly updated. We already have more than ten versions available and we support it with ditavals.

The problem is that the more versions we have, the more ditavals we have and this makes the document more difficult to read and maintain.
I created a subject scheme map to streamline the process and centralize the profiling attributes. However, there are still challenges, among others with links where we can end up with a long list of declarations like here:

Code: Select all

<p>The <uicontrol>Vocabularies</uicontrol> interface of the Back Office is displayed for the 
    <xref href="https://link3.1" format="html" 
        scope="external" product="3.1">tenant</xref>
    <xref href="https://link3.2" format="html" 
        scope="external" product="3.2">tenant</xref>
    <xref href="https://link3.3" format="html" 
        scope="external" product="3.3">tenant</xref>
    <xref href="https://link3.4" format="html" 
        scope="external" product="3.4">tenant</xref>
    <xref href="https://link3.5" format="html" 
        scope="external" product="3.5">tenant</xref>
    <xref href="https://link3.6" format="html" 
        scope="external" product="3.6">tenant</xref>
    <xref href="https://link3.7" format="html" 
        scope="external" product="3.7">tenant</xref>
    <xref href="https://link3.8" format="html" scope="external" product="3.8">tenant</xref>
    <xref href="https://link3.9" format="html" scope="external" product="3.9">tenant</xref>
    <xref href="https://link3.10" format="html" scope="external" product="3.10">tenant</xref> corresponding to the portal as follows:</p>
<image href="../images/bo-setup-vocabularies.png" placement="break" scale="60">
    <alt>Vocabularies interface in the Back Office</alt>
</image>
Thus, is there a way to support and streamline the maintenance of numerous versions? Are the ditavals the best way to distinguish the publications, and would there be a way to make xrefs like shown above more easy to maintain (using keydef for instance)?
What's your opinion?
------
Gaspard
Radu
Posts: 8992
Joined: Fri Jul 09, 2004 5:18 pm

Re: Good practices with multiple versions and ditavals

Post by Radu »

Hi Gaspard,

What are you using for version control? How do you store the DITA XML content?
If we were to take the Oxygen XML userguide for example, we use Git as a version control:
https://github.com/oxygenxml/userguide
and we have branches and tags, for each past release we have a branch, if we want to build the output for that release we do that from the branch. Past userguide releases are not actively maintained anymore, we usually work on the trunk to add documentation for the next release. If we want to make small changes on a past release branch, we just copy them from the trunk.

But I do not know exactly what your product versions mean, if they are all actively maintained, maybe you could keep at least separate DITA Maps for each product version and share the topics. If you were to do that, you could use "keyref" to refer to various links, so your DITA topic would look like this:

Code: Select all

<p>The <uicontrol>Vocabularies</uicontrol> interface of the Back Office is displayed for the 
    <xref keyref="link">tenant</xref> corresponding to the portal as follows:</p>
<image href="../images/bo-setup-vocabularies.png" placement="break" scale="60">
    <alt>Vocabularies interface in the Back Office</alt>
</image>
and then you would have for example a "commons.ditamap" with all the topicrefs and a "product.3.10.ditamap" which would look like:

Code: Select all

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>Product 3.10</title>
	<keydef keys="link" href="https://link3.10" scope="external"/>
	<mapref href="commons.ditamap"/>
</map>
Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
gbv34
Posts: 105
Joined: Thu Jan 20, 2022 12:36 pm

Re: Good practices with multiple versions and ditavals

Post by gbv34 »

Thanks a lot, Radu.
Using a git version control would facilitate the process. I initially thought everything could be managed from a single map with several ditavals because the writers are not necessarily acquainted with GIT. But your solution seems straightforward.
------
Gaspard
chrispitude
Posts: 907
Joined: Thu May 02, 2019 2:32 pm

Re: Good practices with multiple versions and ditavals

Post by chrispitude »

Hi Gaspard,

If your versions are chronological and sequential (each version replaces the previous version), then Git release branches might be a good idea. You can see how we use release branches here:

Releasing output from DITA maps via Git and the Oxygen Publishing Engine

If your versions represent different flavors of content (product A, product B, ...) and they are all published at the same time and share content, then DITAVAL is a good choice.

And these are not mutually exclusive - we use both Git branches for releases, as well as DITAVAL for different product deliverables from the same base content.

The Git plugin makes easy for non-Git users to use Git, but you will need a Git server somewhere as a common place to upload your changes to, and you will likely need at least one Git-knowledgeable person on your team to help with things like branch operations, merge conflicts, and fun things like that.
Post Reply