Search results

DITA: Webhelp with Feedback

You can enable commenting below your webhelp topics by selecting the Webhelp with Feedback skin.

DITA: Webhelp with Feedback

Because documentation on this feature is so scant in Oxygen, I'm elaborating with a bit of detail here.

Setting Up the Feedback System

To set up this commenting system, first create a mysql database and add a user to the database with all privileges. This process is similar for a lot of different sites (e.g., WordPress, Drupal, Joomla), so don't assume this is anything special or difficult. Exactly how you create a mysql database and user depends a bit on your web host.

The instructions in Oxygen focus on using Xampp to set up this database, and they include a specific mysql statement (INSERT INTO `mysql`.`user` ...) to pass in phpmyadmin. You can ignore Oxygen's instructions, as they're poorly written and somewhat misleading. Xampp is for local environments (i.e., a web server emulated on your local computer, not on an actual server on the web). You would only use Xampp for testing purposes, not for actual deployment. The long mysql statement in Oxygen's help is unnecessary if you simply grant the user all privileges to the database (a common configuration).

If you're like most tech writers, you don't have direct access to the servers where you deploy your help content. (That's actually good, because then you don't have to maintain them.) Request from your server admin the following:
  • A server with Apache, MySQL, PHP >=5.16, and PHP MySQL Support. (This is a standard server deployment referred to as a LAMP stack, for linux, apache, mysql, and php.)
  • Create a new MySQL database and add a user to it with all privileges. Ask for the database name, username, and password.

Selecting an identifier

When you transform the webhelp with feedback, you're prompted to use a documentation product ID. Think of your webhelp output as a "product." If you have 3 different webhelp outputs, you have 3 different products, each with their own unique product ID that you specify. Always the same product ID for the same output. This identifier is included in a configuration file so that comments are tied to a particular output. If you're publishing the webhelp files into different directories, consider using the directory name as the product ID.

When you run the configuration to install webhelp with feedback, there's one option that's a bit confusing: ""Display comments from other products. If checked, on this product pages will be visible also comments from other specified products!"

Understanding your webhelp outputs as "products" helps clarify this option. This means if you have two different products, and both have a file name and path such as topics/widgets.dita, then comments made on one instance of topics/widgets.dita will appear on other instances of the the file topics/widgets.dita in other products.

Installing it the first time

The first time you deploy webhelp with feedback, after you FTP the content to your server, go to the /install directory and walk through the installation. You'll be prompted for the database name, database username, password, as well as other configuration options. You can change some of the options later. The installation creates a config.php file in oxygen-webhelp/resources/php/config/config.php where all your configuration options are stored.

The first time you install Webhelp with Feedback, select the check box to create a new database structure. However, on subsequent deployments of other help files, do not select the database structure check box. If you do, your previous database tables will be erased/dropped and your comments removed.

Publishing subsequent revisions

When you publish subsequent iterations of your webhelp, don't upload the /install folder in the output. You only need to upload the install folder first time when you create the installation. On subsequent uploads, just upload the other output files.

Logging in as administrator

When you install Webhelp with Feedback the first time, you're prompted to create an administrator. For subsequent product deployments, you're not prompted to create an administrator account.

Regardless, by default there's a user created named "administrator" that uses the administrator's email address you set up in the configuration. If you forget the admin account, to retrieve the password for the administrator, try logging in to the Admin panel (in the comments area) and choose to reset your password. Once you reset the password and can log in successfully, you can update the password.

Managing comments

Go to a topic in your help, log in as an administrator, and you'll see an Admin button. This takes you to the Admin interface, which is actually shown inside a topic rather than as a separate interface apart from the help system. There you can manage comments and control user roles.

There are three types of notification options: reply notification, page notification, and webhelp notification. The reply notification sends a notification when someone makes a reply to your comment. The page notification sends a notification if someone else adds a comment on the same page. The webhelp notification sends a notification if anyone makes a comment on any page in the webhelp.

There isn't a way to surface an RSS feed or show the latest comments.

Adding Administrators

To enable more administrators, ask a person to create an account. The user will appear in the Admin interface (which you access by clicking the Admin button in the comments area). You can click the user's name and change his or her role and notification options.

Modifying file names versus topic IDs

You can change topic IDs without losing comment history, but you can't change the file names and paths. The file name and path is what connects a topic with the comments associated with it. You can continue to publish updates to the help. If the new topics have the same file name the previous comments remain associated with the new topic. But if you change the file name or path, the comment history for the topic is lost.

Versions

Each time you transform your output, you're prompted to select a version. In the Admin view of the output, you can specify a point in time for comments to appear. For example, you can specify that only comments after version 2.0 can appear. You do this by clicking the Set Version button. Then select the starting version from which comments are visible (meaning visible from that version forward).

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.