Good practices with multiple versions and ditavals
Post here questions and problems related to editing and publishing DITA content.
Good practices with multiple versions and ditavals
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:
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?
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>
What's your opinion?
------
Gaspard
Gaspard
Re: Good practices with multiple versions and ditavals
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:
and then you would have for example a "commons.ditamap" with all the topicrefs and a "product.3.10.ditamap" which would look like:
Regards,
Radu
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>
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>
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Good practices with multiple versions and ditavals
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.
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
Gaspard
-
- 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.
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.
Return to “DITA (Editing and Publishing DITA Content)”
Jump to
- Oxygen XML Editor/Author/Developer
- ↳ Feature Request
- ↳ Common Problems
- ↳ DITA (Editing and Publishing DITA Content)
- ↳ SDK-API, Frameworks - Document Types
- ↳ DocBook
- ↳ TEI
- ↳ XHTML
- ↳ Other Issues
- Oxygen XML Web Author
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Content Fusion
- ↳ Feature Request
- ↳ Common Problems
- Oxygen JSON Editor
- ↳ Feature Request
- ↳ Common Problems
- Oxygen PDF Chemistry
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Feedback
- ↳ Feature Request
- ↳ Common Problems
- Oxygen XML WebHelp
- ↳ Feature Request
- ↳ Common Problems
- XML
- ↳ General XML Questions
- ↳ XSLT and FOP
- ↳ XML Schemas
- ↳ XQuery
- NVDL
- ↳ General NVDL Issues
- ↳ oNVDL Related Issues
- XML Services Market
- ↳ Offer a Service