DITA to WebHelp with Oxygen Feedback: From Authoring to Publishing

This topic guides you through the entire workflow of editing a DITA publication, generating WebHelp Responsive output, and integrating Oxygen Feedback. You can choose between Oxygen Feedback Cloud (SaaS) or Oxygen Feedback Enterprise (self-hosted) for your feedback integration.

Prerequisites

DITA Content Preparation:
- A DITA map file (.ditamap) and associated resources (e.g. .dita/.xml topic files, images).
- Access to Oxygen XML Editor or Oxygen XML Author.
Feedback Integration:
- Decide between:
  - Oxygen Feedback Cloud - Hosted by Oxygen at feedback.oxygenxml.com.
  - Oxygen Feedback Enterprise - Installed and maintained on your own servers (see the installation guide).

Workflow Overview

Edit the DITA Publication:
- Open and edit the DITA map and topics in Oxygen XML Editor/Author.
Generate WebHelp Responsive Output:
- Use the WebHelp Responsive transformation scenario in Oxygen.
Integrate Oxygen Feedback:
- Embed the Feedback HTML fragment into your WebHelp Responsive transformation scenario.
Deploy WebHelp on an HTTP Server:
- Copy the WebHelp output to an HTTP server to make it accessible online.
Access the Published Output:
- Open the WebHelp output in a browser with Oxygen Feedback enabled.

Step 1: Open and Edit the DITA Publication

Procedure

Launch Oxygen XML Editor or Oxygen XML Author.
Open the DITA map file (.ditamap) via the Project view or File > Open.
Edit topics as needed:
- Use Text mode for direct XML editing.
- Use Author mode for a visual, WYSIWYG-style interface.
Save all changes.

Result

The DITA map and associated topics are updated and ready for publishing.

Learn more:

Step 2: Generate WebHelp Responsive Output

Procedure

You can generate WebHelp Responsive output either from Oxygen XML Editor/Author or by using the command line with the Oxygen Publishing Engine.

Option 1: From Oxygen XML Editor/Author

Open the DITA Map WebHelp Responsive transformation scenario in Oxygen XML Editor/Author.
Configure the transformation:
- In the Output tab, specify the local folder where the WebHelp output files will be saved.
- In the Feedback tab, paste the HTML fragment that is obtained during the Feedback site configuration process.
Run the transformation scenario.

Option 2: From the Command Line

Install the Oxygen Publishing Engine on your machine. Refer to the Getting Started Guide for installation instructions.
Prepare the Feedback installation fragment:
- Create an XML file (e.g., feedback-fragment.xml) and paste the Feedback HTML fragment that is obtained during the Feedback site configuration process.
Use the following command to generate WebHelp Responsive output, specifying the path to the Feedback fragment file with the webhelp.fragment.feedback parameter:
```
dita.bat -i path/to/your.ditamap -f webhelp-responsive \
         -o path/to/output/folder \
         -Dwebhelp.fragment.feedback=path/to/feedback-fragment.xml
```
Replace the paths with your actual file locations:
- path/to/your.ditamap - The path to your DITA map file.
- path/to/output/folder - The folder where the WebHelp output will be saved.
- path/to/feedback-fragment.xml - The path to the XML file that contains the Feedback fragment.

Result

The WebHelp Responsive output (HTML5 files and associated resources) is generated:

If using Oxygen XML Editor/Author, the output is saved in the folder configured in the transformation scenario, and the main page of the output opens in the default browser.
If using the command line, the output is saved in the directory specified in the -o parameter.

Learn more:

Step 3: Integrate Oxygen Feedback

Procedure

Oxygen Feedback Cloud:
- Log in at feedback.oxygenxml.com.
- Create a Site Configuration, specifying the base URL where your WebHelp will be deployed.
- Copy the provided HTML fragment.
Oxygen Feedback Enterprise:
- Install and configure the Feedback service on your server (installation guide).
- Log in to the administration interface and create a Site Configuration.
- Copy the generated HTML fragment.
Embed the HTML fragment into the Feedback tab of the WebHelp transformation scenario.

Result

The Feedback HTML fragment is successfully embedded into the WebHelp Responsive transformation scenario, enabling commenting functionality in the output.

Learn more:

Create a Site Configuration

Step 4: Deploy WebHelp on an HTTP Server

Procedure

Transfer the WebHelp output (HTML5 files and resources) to an HTTP server (e.g. Apache HTTPD, NGINX).
Ensure the server is configured to serve the WebHelp content via a URL using http or https.

Important Notes:

The WebHelp content must be accessible via the internet or local network using a URL (e.g. http://server-name/...).
The Oxygen Feedback component will only function when accessed via an HTTP(S) URL. It will not be displayed properly when opening files directly from a local system (file:// URLs).
This step must be performed by a System Administrator with access to the organization’s servers.

Result

The WebHelp Responsive output is deployed on the HTTP server and accessible through a browser using the associated URL.

Step 5: Access the Published Output

Procedure

Open a web browser and access the WebHelp output using the server’s URL.

Result

The WebHelp content is displayed, and the integrated Oxygen Feedback component (e.g. comment sections) is functional and visible.

Additional Resources

Webinars:

By following this workflow, you can seamlessly author, publish, and integrate Oxygen Feedback into your WebHelp Responsive output, ensuring an interactive and accessible user experience.