Editions And Versions Overview

In This Topic

The Document! X Editions and Versions functionality helps you to publish multiple variations of your Browser Help output, allowing the end users of your Browser Help output to switch between different Editions and/or Versions.

Editions define multiple variants of the same Browser Help output that you generate using Build Profiles. As an example, you might generate three different outputs (by leveraging Build Profiles and the Document! X Single Sourcing features) for Standard, Professional and Enterprise Editions of your Software Product. Each Edition relates to the single Build Profile that generates the Browser Help output for that Edition.

Versions define chronological published versions of your documentation. As an example, after three software releases you might define three versions; 1.0, 1.1 and 2.0 relating to the software update versions. Each time your Software Product is updated, you would define a new Version and set it as current.

You can use just Editions, just Versions, or define them both if you would like your documentation users to switch between both Editions and Chronological Versions of your published Browser Help output.

If you publish just a single variant of your Browser Help output and do not wish to allow your end users to switch between different Chronological Versions (i.e. you only ever publish a single current version of your Browser Help Output), then Editions and Versions functionality is not something you will need to use in your project.

Switching between different Editions and Versions in the generated output requires that you publish your Browser Help output to an intranet or internet URL. Editions and Versions functionality does not work when you are viewing content saved to a local drive.

Example Editions and Versions Usage Scenarios

The Night Sky software product is updated approximately once a year. The version about to be released is 1.0. The application itself is a Windows Desktop application, but the online help is browser-based and hosted on the Night Sky software Azure Hosted web site.

In the future, end users might be using different versions of the Night Sky application and it is essential that the users are able to access the version of the online help specific to the version of the application they are using.

The Document! X project for the Night Sky documentation already contains two Build Profiles that generate output for the Free and Professional Editions.

Initial Setup

The Night Sky documentation would benefit from the ability to switch between Editions and Versions. The ideal initial setup for Editions and Versions for this scenario is therefore:

Define two Editions - "Free" and "Professional". Each Edition is associated with the existing Build Profile in the Editions and Versions editor.
Define a single version "1.0" and set it as the Current Version in the Editions and Versions editor.
Define a Publishing Target for both Build Profiles in the Build Profile Editor. The Publishing target for both Build Profiles publishes to the same target URL. The Editions and Versions configuration automatically publishes each Build Profile beneath a child path specific to the Edition and Version being published.
The Browser Help output for Edition of 1.0 is thereby automatically published to a different URL that can be opened by the Night Sky application according to the installed Edition - Free or Professional.

Once configured, built and published, users of Night Sky 1.0 Browser Help see an "Editions" selector in the generated Browser Help output that allows them to switch between documentation for the "Free" and "Professional" Edition documentation. At this point, there is no "Version" selector in the generated Browser Help output as there is only a single version defined.

Subsequent Versions

For each subsequent version of the Night Sky software:

A new version (e.g. 2.0) is defined in the Editions and Versions editor.
The new version of the documentation is built and published.
Each Edition of the new version is automatically published to a different URL (and a different URL from 1.0) that can be opened by the Night Sky 2.0 application according to the installed Edition.

Once configured, built and published, users of Night Sky 2.0 see both an "Edition" selector to allow them to switch between documentation for the "Free" and "Professional" Edition, and also a "Version" selector to allow them to switch between the different published versions of the documentation.

Users of Night Sky 1.0 now also see both the "Edition" and "Version" selectors. This happens automatically thanks to the updated Editions and Versions configuration file shared by both 1.0 and 2.0, and does not require that the 1.0 documentation is modified or republished.

The Photo Edit software product is updated approximately twice a year. The version about to be released is 1.0. The application itself is a Windows Desktop application, but the online help is browser-based and hosted on the Photo Edit Azure Hosted web site.

In the future, end users might be using different versions of the Photo Edit application and it is essential that the users are able to access the version of the online help specific to the version of the application they are using.

Initial Setup

The Photo Edit documentation would benefit in future (i.e. from 1.1 onwards) from the ability of documentation readers to switch between the documentation for different Versions. The ideal initial setup for Editions and Versions for this scenario is therefore:

Define a single version "1.0" and set it as the Current Version in the Editions and Versions editor.
Define a Publishing Target for both Build Profiles in the Build Profile Editor. The Editions and Versions configuration automatically publishes beneath a child path specific to the Version being published.

Once configured, built and published, users of Photo Edit 1.0 Browser Help not initially see a "Version" selector in the generated Browser Help output as there is only a single version defined.

Subsequent Versions

For each subsequent version of the Photo Edit software:

A new version (e.g. 1.1) is defined in the Editions and Versions editor.
The new version of the Browser Help output is built and published.
The Browser Help output for the new version is automatically published to a URL specific to 1.1 which can be opened specifically by the Photo Edit 2.0 application.

Once configured, built and published, users of Photo Edit 1.1 see a "Version" selector to allow them to switch between the different published versions of the documentation.

Users of Photo Edit 1.0 now also see the "Version" selector. This happens automatically thanks to the updated Editions and Versions configuration file shared by both 1.0 and 1.1, and does not require that the 1.0 documentation is modified or republished.