Setting up a comment feature for online Help

Not everything that is technically possible makes sense conceptually. Therefore, the question of whether and where a comment feature is useful at all and where it may even prove detrimental, is raised at the very beginning. A full treatment of this question would fill an entire post, so only a brief summary of the advantages and disadvantages of a comment feature is given at this point.

Advantages:

• Users feel involved in the development of the product.  This encourages customer loyalty.
• Manufacturers get real-world feedback about weak points in the product and documentation.
• The technical editor gains insight into actual usage scenarios.

Disadvantages:

• The contributed information may be incorrect, incomplete or “politically undesirable”.
• The contributed information may be difficult to understand.
• If an evaluation feature is incorporated and the evaluations are negative, then the credibility of the associated document decreases.

Hence, it must be well thought out whether a comment feature should be integrated or not. Perhaps, only certain parts of the documentation or only certain topics are suitable for it.

In any case, a fairly large number of users who are ready to contribute actively to the contents are required. This is rarely more than one percent of all users. Hence, the technical editing team itself should be active in the beginning and initiate discussions. In addition, a person belonging to the company should be responsible for checking the content and act as the moderator.

The basic components

All solutions consist of the so-called frontend and backend. The frontend includes the comments and evaluations in the Help topic and displays a form for entering the comments - Figure 1.

Fig. 1: Front end for the user, implemented here with www.cubescripts.com.

The backend is a web-based user interface that enables you as administrator to confirm, delete and edit the comments and evaluations – Figure 2.


Fig. 2: Back end for administrators, using the example of www.cubescripts.com.

Individual settings and format requirements are set either using configuration files and style sheets or even through the backend.

Comments and evaluations work only with an uncompiled Help that can be displayed directly in the Internet browser. Also, the online Help must be on a web server, as PHP code needs to be executed for the integration. If you want to address a comment function from a CHM file, this is possible only in an indirect way, such as via a pop-up or iFrame. Some hosted solutions, however, work with JavaScript also as we will show later.

Solutions in authoring tools

Only a few Help authoring tools offer a built-in feature that allows you to integrate comments and evaluation features at the press of a button. Some of these features are also very expensive. An overview:

• In Adobe AIR Help with "Adobe AIR Comments", RoboHelp offers a built-in functionality for comments, but only in Adobe AIR format and not for any other browser-based Help.
• For Flare, there is a complementary product "MadCap Feedback", which costs about $1,800.
• A complementary product is available for HelpStudio and Document! X also. The "Community Extensions" package costs around €1,100.
• Help & Manual offers a simple connection to the Internet services "IntenseDebate" and "Disqus" in the optimal premium pack that costs €80.

Solutions by providers

If your authoring tool does not provide any feature to integrate comment and evaluation features, the simplest solution is to use an external provider. In some cases, such "hosted services" are even free. What are the pros and cons?

Advantages:

• no separate SQL database required and no separate server with PHP support required
• mostly JavaScript-based, without PHP on one’s own page
• minimum configuration effort

Disadvantages:

• dependence on the availability of the respective service
• data is not on your own server
• rather unprofessional appearance, if the user notices that an external service is used

Steps for integration: When you register, you receive an ID from the provider. You enter the ID in one or two ready-made JavaScripts. Then you add the JavaScript in place of your topic template, where the comments and the links to the comments should appear.

Now when you generate the Help, the comment feature is already integrated. You can manage the comments via the online access of the provider.

Providers - the best known services that are free of cost at least in the basic version:

• DISQUS
• IntenseDebate

Commercial script solutions

Most of the commercial solutions are PHP scripts with a more or less comfortable backend. The installation, integration and usage do not differ significantly from the open source systems described in the next section.

For example, configuration is much easier with the XcommentPro software, which costs about $100. Here, you can set important settings and formats through a graphical user interface and do not have to manually intervene in the style sheets.

Providers - the following web sites provide a good overview of commercial scripts:

• www.hotscripts.com/categoryphp/scripts-programs/reviews-ratings/
• http://codecanyon.net/searches?term=comment&type=files

Free script solutions

Although there are only a few open source programs to incorporate comments and evaluations, they are at par with the commercial products.

Examples of open source scripts are:

• www.commentics.org
• http://ratherodd.com/commentator/

In the following sections, we will show you the installation and integration using the example of the script solution Commentics 1.5. Setting up Commentics is not a difficult task even if you have no experience in installing on a web server.

Help & Manual is used for our online Help example. However, the principle is the same for all authoring tools. The only requirement is: The templates underlying the Help pages must be editable in HTML. At least you should be able to insert HTML snippets there. This condition is fulfilled by all professional Help authoring tools today, sometimes even by some of the tools under 100 €.

For the installation, you need a web server with PHP and SQL as well as FTP access to this server:

• If your company operates its own web server, you need to contact your system administrator.
• If your company uses the services of a provider, you need access to the administration area of your internet package. With almost all providers, you can make the necessary functions and settings easily via a web-based user interface.

To test the script solution, you can also install a web server locally. For Microsoft Windows, free packages are available, including installation programs:

• XAMPP
• MoWeS Portable
• WampServer

Apple Macintosh users can use Mamp.

Step 1 Create database: In the first step, you need to create a SQL database on your server. This is usually a button on the administration interface of your Internet provider. Note the database name, user name, password and host name.

Step 2 Download, unzip and customize the script: Download the comment script that you want to use from the Internet. Unzip it to a directory on your local hard disk.

In one of the script files, you must now enter the previously noted details of your database, in Commentics, this is the file "connect.php"  - Figure 3.

Fig. 3: Enter details of your database.

Step 3 Upload script and set access rights: Now upload the entire script via FTP to your web server. Be sure to set the permissions for the files as described in the documentation of the script. It is easy to adjust the rights using an FTP program like FileZilla: Just click on the file with the right mouse button and set the required permission. In Commentics, you must set the permissions for the file connect.php as 444 - Figure 4

Fig. 4: Adjust access rights using an FTP program – here FileZilla.

Step 4 Execute installation script: Finally, open the installation script that requests additional information step by step from you, for example, the user name and password for the backend - Figure 5.

Fig. 5: The installation script of Commentics.

Finally, the installation script creates all the required fields in the database.

Step 5 Integration into the production process of the online Help: To integrate into your online Help, add the three snippets of HTML and PHP code that have been provided, to your topic template - Figure 6.

Fig. 6: Code snippets inserted into the topic template.

Important in Commentics: There should be no blank line and no spaces before the first snippet.

While generating your Help, you must make sure that the topics are not created as *.htm or *.html files, but as *.php files. Most authoring tools have the appropriate defaults in the export settings.

In some PHP installations,  “UTF-8 byte order mark" may result in errors if it is set. Therefore it should not be set - Figure 7.

Fig. 7: Export settings in the Help authoring tool - here Help & Manual.

If your authoring system does not offer any PHP output, you can rename the HTML files themselves. It is best to use a suitable tool for searching and replacing, because you need to change not only the file name, but also all links and other references within the files. The following tools may be used for this:

• PowerGREP, about € 119
• Text Workbench, about $ 50
• AKS Text Replacer, about $ 40
• FART, Open Source
• Swiss File Knife, Open Source
• Rainbow, Open Source

If you upgrade your Help more frequently, then you should make sure that the search and replace starts at the command line level.

Alternatively, you can also configure a web server such that the PHP code is also executed in HTML files. This eliminates the searching, replacing and renaming of files.

Step 6 Copy the online Help to the server: Since your online Help is now in the PHP format, it can only be accessed on a server with PHP support. Copy all the data belonging to the Help via FTP to your web server. Now when you call the Help, a comment field is available in each topic - Figure 8.

Fig. 8: Topic with comments, converted with Commentics without changing the style sheets provided.

You can manage all the comments from the backend as administrator. You can also set which fields are displayed to the users while entering comments via the user interface - Figure 9.

Fig. 9: Managing the comments in the backend - here Commentics.

Step 7 Customise design: If everything works as intended, you should finally adjust the design of the comments to the design of your online Help. This can be done by editing the linked CSS file.

Expanding search

Almost all of the proposed solutions have a disadvantage: The text of the comments is not indexed by the full-text search of the online Help.  Currently, only RoboHelp has the feature of including external sources in the search. If you want to include comments in the search index in other solutions, you must replace the default search through a custom search routine. Solutions that can be integrated with a few lines of code are available for this also. However, in most cases, one can live with the restriction on the scope of search. There are even reasons to exclude comments from search, so as to take the user directly to the given content and view comments only as an addition.

Conclusion

To provide a comment and evaluation feature in an online Help, your authoring tool need not support the integration of such a feature explicitly. The easiest alternative is to use the service of a specialized provider for the comments and evaluations. Apart from including a small ready-made JavaScript snippet, you need not change anything else in your online Help.

If both the online Help as well as the database for the comments lie on your own server, then there are ready-made commercial and freely available PHP scripts for this. Installing a script on your server and including it in your online Help can be accomplished even without in-depth programming and IT skills.

But whether integrating a comment and evaluation feature in an online Help is always useful is another question altogether. Even if such features are now found in more and more places, they are useful only if a sufficiently large number of users contribute content and a moderator reviews the comments and evaluations continuously.