by Suzette Leeming

I ventured into the online help world in the mid 90’s and reviewed a few different help authoring packages at that time, such as HelpBreeze, Doc-to-Help, and RoboHelp. At that time, almost all help authoring packages used Word. I went through a similar review around 2005, although my needs had changed; I wanted a single-source solution that didn't use Word. When I was offered the opportunity to review Doc-to-Help 2009, I eagerly looked forward to seeing how much the software had evolved and to seeing whether or not it was still dependent on Word.

Installation

I downloaded and installed both the Enterprise version of Doc-to-Help 2009 and the Dynamic Help Add-On – Studio Net Winforms. Unfortunately, I wasn’t able to test Studio Net, since it works with dot net applications, which we don’t use. This review therefore, is limited to using Doc-to-Help 2009.

Documentation

One would think that as a technical writer I would be the first one to use the documentation, but I actually prefer to approach an application by playing with it, and tend to only use the documentation when necessary. This approach gives me the opportunity to determine how intuitive an application is. I needed to use the documentation in this situation though, because I was locked into a mindset of how my current help authoring software (Help and Manual) worked, and Doc-to-Help is quite different.

Doc-to-Help’s own documentation is quite impressive. A Getting Started wizard walks the user through the initial setup:

Besides the online help, there are demos available on their website, a How-To library of webcasts and online help mouse-overs for buttons.

Training manuals and formal training are also available for a cost. All of which is really helpful, as I found this software had a steep learning curve. I accept some of the responsibility for that though – the interface has been designed to be similar to Office 2007, which I don’t use and am not familiar with. Anyone who is familiar with Office 2007 though should find this interface easy to understand and to navigate. Dynamic Help was available as I used the application and showed relevant information depending on where my mouse was pointing in the window. From the Dynamic Help, I was able to access the complete help documentation for Doc-to-Help 2009.

For someone new to help authoring, Doc-to-Help 2009 also has a tutorial on single sourcing, which would be quite useful.

Features and Functions

Doc-to-Help 2009 allows users to work in Word, HTML, XML, or the built-in editor. Documents can be imported from Word, XML, HTML, RoboHelp, HTMLHelp, and WinHelp. It features an index editor, TOC editor, theme editor, CSS editor, and a glossary editor. It’s ideally suited for a multi-authoring environment.

Importing

I prefer not to work in Word, so all of my current files are in Help and Manual. Unfortunately, I couldn’t find a way to import them into Component One’s Doc-to-Help 2009, even though they are in an XML format. There were errors with the imported files and they weren’t usable. When I selected to import HTML files, the options given were to import RoboHelp HTML or HTML Help. I generated HTML Help from Help and Manual, but Doc-to-Help 2009 wanted the .hhp file, which Help and Manual didn’t give me. I don’t blame Doc-to-Help for my difficulties, the problem could very well be with the way Help and Manual formats their XML files.

So, I created a new project in Doc-to-Help 2009. There was the option to copy settings from an existing project, and to use full styles, a minimal group of styles, or to add your own styles. The default output was selected upfront and the software gave me the option to define the initial document type – XHTML, Word, HTML, an imported file, or no initial document type – which uses the built-in editor. The built-in editor can only be used when editing XHTML documents.

Functionality

Doc-to-Help 2009 is impressively versatile. Attributes and builds are assigned to each topic; the defaults ones are Internal and Release. These attributes and builds are used with the conditional text features. I really liked how styles could be added to conditional text; depending on the build you are producing, the styles can be different. The conditional text was easy to use and text with variables could also have conditions applied. Text could be marked conditional to a specific platform, target, or attribute.

For each topic, a topic type is assigned. The topic types are Conceptual, Contents, Glossary of Terms, Glossary Term Definition, Margin Notes, Procedural, Sub-Contents, and What’s This? One thing I found was that assigning Topic Types really allowed for true re-use of information. I could re-use the Conception type topics in marketing material, and the Procedural topics in training materials. The Auto-Indexing feature allows you to select which topic types to include.

Templates were available and could also be customized. You can customize the template for all help formats, topics, styles, printed manuals, CSS, etc. Each of the Help targets has a corresponding template, which contains paragraph and character styles, and uses Cascading Style Sheets (CSS), based on the styles. This is particularly useful for users who don’t have any knowledge of CSS.

The Doc-To-Help Markup Language is a set of predefined styles that can be used to mark up source documents and create topic links, keywords, groups, and conditional text, as well as insert variables. When a style is applied to text, a hot spot is created. Doc-to-Help automatically converts cross-references into hyperlinks, and hyperlinks can also be added by highlighting a block of text and clicking the Link button on the toolbar.

Graphics and multimedia files were imported by reference, which is always my preference. Variables were easy to define and use. The index and glossary editors were extremely user-friendly. I particularly like the glossary features, since my current software does not do glossaries easily. In Doc-to-Help 2009, you define the Glossary Terms and then the Glossary Definitions.

The Table of Contents is created automatically based on the sequence of topics. The default structure can be overridden through the project window. When the table of contents has been edited manually though, new topics are no longer added to the table of contents automatically.

I initially found the process for adding keywords to be a bit cumbersome. To add a keyword, you need to go into Index and Groups and click Keyword. Once the keywords have been added, they need to be assigned to a topic. I ended up really liking the way keywords were added though, as this way helps to control the list of keywords, and you won’t end up with multiple keywords that are just a variation of the same word, for example, “Initialize”, Initializing”, “Initialized”, etc. This is definitely a better way of handling keywords.
Topic lists can be printed or exported and can be filtered. This can be used to give a list of Topic and Context IDs to developers so that context-sensitive help can be implemented.

There are many reports that are available from Doc-to-Help 2009, including:

• Help Contents Listing
• Help Index Listing
• Index Report by Group
• Index Report by Keyword
• Index Report by Topic
• Script Listings
• Style Definitions
• Topic Detail Report
• Unindexed Topic Report

I wasn't able to evaluate the Team Authoring functionality (available in the Enterprise version), since I'm a lone technical writer, however Doc-to-Help's documentation states that project changes are available to the entire team, and one author's changes will not be overwritten by another author's changes.

Doc-to-Help's team authoring is a basic source control feature in which authors work on their own local copy of a project on their machine (called the working copy), while the master project is located on a network or on a Web server.

Projects are uploaded to a central repository, where they become a team project and the local copy becomes the user's working copy. Other team members connect to the central team project and create their own working copies. When documents are checked out and worked on by one team member, they become locked so that other users cannot edit it until the original member checks it back in. Each user's working copy is updated using special commands to send (check-in) changes or to get other users' changes. All team members must have the same version & build of Doc-to-Help 2009 and use the same templates/styles.

Output

When ready to produce the help files or manuals, the user clicks on a "Build" button. The output options are standard - Help 2.0, HTML Help, JavaHelp, Manual (printed), NetHelp & WinHelp.

The Manual option produces a Word document. I would prefer if it produced a PDF file. I suppose the thinking is that "everyone" has Word. The help said I could check "Generate PDF Target" in the Help Topic dialogue box, which I did, but when I rebuilt my project, it still just showed the Word document - I had to go look in my project file for the PDF.

Help 2.0 required the HxComp.exe help compiler, and I understand this type of help is used with Microsoft Visual Studio applications. The output resembled the MSDN type of help. The Namespace and Parent Namespace are set up in the Help Targets dialog box. As well, if the Help 2.0 executable file was not in the default location, it had to be specified.

Doc-to-Help Java Help required the Java Runtime Environment files to be installed and the environment variables had to be updated to tell Doc-to-Help where to find the Java files.

As expected, WinHelp output generated an RTF file (there's that Word thing again), since WinHelp had a Word dependency; I haven't actually used that format in about 10 years. HTML Help didn't require Word, and generated quite well.

NetHelp (aka WebHelp, Browser-based Help) created a set of html files.
Overall, I was very impressed with the flexibility and functionality of Component One's Doc-to-Help 2009. I would have liked to be able to work without even know that Microsoft Word exists though, especially when working in HTML, XML or the build-in editor. I think that would make Doc-to-Help a truly “single-source” solution.

The downside to Doc-to-Help is the steep learning curve, which Component One has tried to address with their multitude of training/learning venues. I was so impressed with Doc-To-Help 2009 that if I could covert my current help files, I would seriously consider switching help authoring tools! On a rating scale of 5, I would give this help authoring tool 4.5.

Technology

• Doc-To-Help

Writing and Editing

• Reviews