Advice needed for WebHelp with 2 versions of a software product
-
sopuli
- Posts: 15
- Joined: Fri Jul 11, 2025 2:22 pm
Advice needed for WebHelp with 2 versions of a software product
Hello community and Support Team,
First some background:
Our software product has 2 versions (V8.1 and V8.2).
Version 8.1 is the extensive base version. Version 8.2 is the base version plus only a handful of new topics.
In oXygen, all topics for the base version 8.1 are not tagged with the "product" attribute.
All topics for version 8.2. have been tagged with the attribute "product" as V8.2.
So far, I used to create one WebHelp output for V8.1. I simply uploaded the oXygen WebHelp output folder as a ZIP into a dedicated folder onto our web server where a script would unpack it overnight. Easy.
From now on, my WebHelp is supposed to be able to allow users to choose which version they are using - to only see relevant documentation. I understand that I need to include a version switch (which is not the topic for this question...)
According to my research, I will need to create one transformation for V8.1 with DITAVAL excluding all 8.2 content, and another transformation for V8.2 without any DITAVAL.
I then need to upload both webhelp folders onto our webserver, so that a version switch can access the relevant topics.
Now my actual questions:
1) Does my handling of the versions in oXygen sound technically correct and is it Best Practice?
2) How does the setup on the web server need to look like when I upload two webhelp output ZIP files:
- Do I need to upload both webhelp output ZIPs into the same folder on the web server?
- What is important with regards to naming the zipped files and the script that unpacks them?
(In your reply, please bear in mind that I have no programming skills.)
Thank you so much in advance
Best wishes
Herdis
First some background:
Our software product has 2 versions (V8.1 and V8.2).
Version 8.1 is the extensive base version. Version 8.2 is the base version plus only a handful of new topics.
In oXygen, all topics for the base version 8.1 are not tagged with the "product" attribute.
All topics for version 8.2. have been tagged with the attribute "product" as V8.2.
So far, I used to create one WebHelp output for V8.1. I simply uploaded the oXygen WebHelp output folder as a ZIP into a dedicated folder onto our web server where a script would unpack it overnight. Easy.
From now on, my WebHelp is supposed to be able to allow users to choose which version they are using - to only see relevant documentation. I understand that I need to include a version switch (which is not the topic for this question...)
According to my research, I will need to create one transformation for V8.1 with DITAVAL excluding all 8.2 content, and another transformation for V8.2 without any DITAVAL.
I then need to upload both webhelp folders onto our webserver, so that a version switch can access the relevant topics.
Now my actual questions:
1) Does my handling of the versions in oXygen sound technically correct and is it Best Practice?
2) How does the setup on the web server need to look like when I upload two webhelp output ZIP files:
- Do I need to upload both webhelp output ZIPs into the same folder on the web server?
- What is important with regards to naming the zipped files and the script that unpacks them?
(In your reply, please bear in mind that I have no programming skills.)
Thank you so much in advance
Best wishes
Herdis
-
julien_lacour
- Posts: 778
- Joined: Wed Oct 16, 2019 3:47 pm
Re: Advice needed for WebHelp with 2 versions of a software product
Hello Herdis,
You’re on the right track: you should generate distinct outputs, one per version, because the WebHelp Responsive transformation is scoped to produce a single output.
However, relying only on DITA profiling attributes to handle multiple versions can be quite limiting, especially when you need to manage many of them. I strongly recommend using a version control system such as Git instead, where each version corresponds to its own branch.
That said, once having both versions generated, you need to make sure each of them is deployed in its own directory and not in the same folder. I'm not aware of how you unpacking script works but you need to ensure the name of the output directory differs.
Finally, and with the help of this template, you should be able to create a version selector, leading to one or the other version (by changing the output directory in the URL for example).
Regards,
Julien
You’re on the right track: you should generate distinct outputs, one per version, because the WebHelp Responsive transformation is scoped to produce a single output.
However, relying only on DITA profiling attributes to handle multiple versions can be quite limiting, especially when you need to manage many of them. I strongly recommend using a version control system such as Git instead, where each version corresponds to its own branch.
That said, once having both versions generated, you need to make sure each of them is deployed in its own directory and not in the same folder. I'm not aware of how you unpacking script works but you need to ensure the name of the output directory differs.
Finally, and with the help of this template, you should be able to create a version selector, leading to one or the other version (by changing the output directory in the URL for example).
Regards,
Julien