Document! X 2019
In This Topic
    Editions And Versions Overview
    In This Topic

    The Document! X Editions and Versions functionality will help 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 3 different outputs (by leveragin 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 3 software releases you might define 3 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.

    Example Editions and Versions Usage Scenarios

    Example 1: Online help for a "Night Sky" software product available in Free and Professional Editions

    The Night Sky software product will be 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 2 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:

    1. Define 2 Editions - "Free" and "Professional". Each Edition is associated with the existing Build Profile in the Editions and Versions editor;
    2. Define a single version "1.0" and set it as the Current Version in the Editions and Versions editor;
    3. Define a Publishing Target for both Build Profiles in the Build Profile Editor. The Publishing target for both Build Profiles will publish to the same target url; the Editions and Versions configuration will automatically publish each Build Profile beneath a child path specific to the Edition and Version being published.
    4. 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 will see an "Editions" selector in the generated Browser Help output that will allow 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:

    1. A new version (e.g. 2.0) is defined in the Editions and Versions editor;
    2. The new version of the documentation is built and published;
    3. 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 will 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 will 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.

    Example 2: Online help for a "Stock Tracker" web application available in Free and Professional Editions

    The Stock Tracker web application is available in Free and Professional Editions, with different functionality available in the different Editions. The application and the documentation are Browser Based and hosted on an Apache web site.

    The Document! X project for the Stock Tracker web application documentation already contains 2 Build Profiles that generate output for the Free and Professional Editions.

    Setup

    The Stock Tracker documentation would benefit from the ability to switch between the documentation for Free and Professional Editions. The ideal initial setup for Editions and Versions for this scenario is therefore:

    1. Define 2 Editions - "Free" and "Professional". Each Edition is associated with the existing Build Profile in the Editions and Versions editor; No versions are defined as there will only ever be a single current version of the documentation published;
    2. Define a Publishing Target for both Build Profiles in the Build Profile Editor. The Publishing target for both Build Profiles will publish to the same target url; the Editions and Versions configuration will automatically publish each Build Profile beneath a child path specific to the Edition being published.
    3. The Browser Help output for each Edition is thereby automatically published to a different url that can be opened by the Stock Tracker Web Application according to the Edition being used - Free or Professional. 

    Once configured, built and published, users of the Stock Tracker Web Application Browser Help will see an "Editions" selector in the generated Browser Help output that will allow them to switch between documentation for the "Free" and "Professional" Edition documentation.

    Example 3: Online help for a "Photo Edit" Desktop application available in a single Edition

    The Photo Edit software product will be 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:

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

    Once configured, built and published, users of Photo Edit 1.0 Browser Help will 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:

    1. A new version (e.g. 1.1) is defined in the Editions and Versions editor;
    2. The new version of the Browser Help output is built and published;
    3. 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 will see a "Version" selector to allow them to switch between the different published versions of the documentation.

    Users of Photo Edit 1.0 will 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.

      

    See Also
    Editions And Versions Fundamentals

     

     

    © 2019 Innovasys. All Rights Reserved.

    Send Feedback