Elsinore made the decision to switch from Compiled HTML Help edited with RoboHelp to a wiki-based help system using Screwturn Wiki. The following is a look into the decision making process that ultimately lead to replacing RoboHelp with a Wiki.
Issues with RoboHelp
In general, we were very frustrated with RoboHelp. After using it for many years and through several versions of our product, we had assembled a critical mass of grievances.
-
Lack of flexibility around updates which were not tied to releases
-
Rigidness of source code control and upgrade pains
-
Web Help required rebuild of the entire project to generate .htm files, which took 10-15 minutes and required additional files to be checked into source control and then picked up by the Product build system. This often resulted in internal builds not having updated Help files installed.
-
Updates simply took too much time, effort, and planning. When a new help resource is available, we want to make it available quickly and effortlessly.
Advantages of Wiki for Product Help
-
Updates made in real-time
-
Ability to easily link to other sources of rich content (tech tips, how-to videos, blog entries, developer labs articles, etc.)
-
No need for product to "phone home" for help updates
-
Source code available so customers can deploy on own network
-
Extremely easy for staff to update
-
Freedom from RoboHelp compatibility issues
-
Free to near-free
Disadvantages of Wiki for Product Help
-
Difficult to compile for a printed manual
-
Difficult to implement context-sensitive help
-
Conversion of existing data from RoboHelp into new format takes time
-
Traditional version control approaches must be rethought
The idea of converting a large existing documentation base from RoboHelp to wiki format can be daunting. In the end we found that it would be easier to manually convert from RoboHelp to wiki than to convert from our older RoboHelp version to newer versions. The manual conversion also dovetailed nicely with a comprehensive review and update of the documentation. There are also some conversion tools out there such as the RoboHelp2Wiki tool, which may be useful in the right situations.
We went with Screwturn Wiki over the other available variants for the following reasons:
- ASP.NET
- File-based
- Easy Xcopy deployment, with no need to configure outside dependencies
Summary
In the end, the ease of use and extensive flexibility of the wiki format made this an easy decision. Our priority was to update our help on a real-time basis with a minimum of frustration for our internal staff, and those goals were best achieved by converting our help from RoboHelp to a wiki.