Why Voxeo is using HelpServer

James 'Van' Vanslette explains how Voxeo have implemented their first content management system.

After an 18-month research project conducted by the documentation team, our organization’s leadership at Voxeo headquarters located in Orlando, Florida gave the proverbial ‘thumbs up’ to switch from a hard-to-manage, proprietary, wiki-based documentation platform to the fully fledged HelpServer content management system. Voxeo is the industry leader in automated voice response platforms and we are absolutely obsessed in our ability to keep our customers informed.

The research project eventually focused on the features available in Adobe RoboHelp Server 9, Author-it, Madcap Flare, and 4.ST HelpServer.  At the time, we were considering Software as-a-Service as well as in-house installations. Specifically, we were interested in structured content, WYSIWYG editor, real-time publishing, version control, team authoring, customer feedback, and most importantly, the client had to run on the Apple Mac OS X platform. Hands down, we chose HelpServer to serve our documentation to the public as shown in Figure 1.

Figure 1: Voxeo Documentation Portal

Support

At Voxeo, we pride ourselves on our customer obsession. Naturally, we wanted, and expected the same kind of support from our vendors. We first met with HelpServer representatives at a technical communicators’ convention and were impressed by them.

Even while we evaluated the trial version of HelpServer, their customer support responded and implemented solutions specific to our organization’s needs.  And still today, a question or issue gets a response or solution within 24 hours.

We opted for on-site HelpServer training at their headquarters in Leuven, Belgium.  The support team tailored the training to our specific implementation requirements and provided the information in an easy-to understand interactive presentation.  After implementation, HelpServer support followed up with several online web meetings.  The HelpServer support team is just awesome.

Installation

We decided to use an on-premise system with options for web-based authoring as well as local clients, workflow management, customer feedback, Smartcontent, and notification.  The Voxeo leadership loved the great price, and the documentation team loved the whole package!

We elected to install HelpServer on a Linux operating system using a MySQL database and an Apache TomCat web server. Although the integration documentation for the HelpServer installation was a bit vague, with the help of our IT department, we were up and running within an hour.  Since HelpServer is Java-based, it works well on any platform or web browser we use.

Import

Our first task was to figure out what to do with our legacy content. Some of it was wikibased HTML, some in Microsoft Word format, and much of it in a proprietary HTML-like set of source files. HelpServer came to our rescue.  Importing HTML was easy using their batch importing. On import, you can map the HTML tagging to new styles that you want to use in HelpServer.  This has saved us a ton of time!

However, our Microsoft Word formatted documentation was another story.  While HelpServer will import Microsoft Word format, the operating system has to be Microsoft Windows, which makes sense as Microsoft Word is a Microsoft Windows product.  So we opened HelpServer on a Microsoft Windows platform, imported the files, and then got back to work on our Macs.

Besides HTML and Microsoft Word, HelpServer can import Author‑it XML, DITA, WinHelp, RoboHelp HTML, RoboHelp Word, and more.

How it works

In HelpServer, one of the most unique features is that the content is abstracted away from the structure. Content is stored in the database as objects, whereas the content structure is defined by references, much like a hyperlink in a web page. For example, if you import a Microsoft Word document, the file is stored in  the database and anytime you use all or part of the content within the document, HelpServer creates the content based on an object reference to the Microsoft Word document. This means you can reuse the content in multiple places without ever changing the source document.

To re‑use content, you can copy or clone.  When you copy a topic, you are really only copying the object reference. So when you paste, you are really pasting just a link to the copied content. Anytime you edit the source or the copied content, both instances are updated at the same time. When you clone an object, you share the current version of the object, which can be edited without affecting the source. End-user content is created dynamically on request for each user. Based on the log in (or the lack of a log in), user content is created dynamically and displayed using the object references. When you publish a change, it is immediately reflected the next time a user opens or refreshes that page.

With the HelpServer Smartcontent feature, you can tailor the dynamically created content for each type of user. We haven’t used this feature very much at Voxeo yet, but we plan to by displaying detailed content to new users, and for advanced users, a more succinct documentation set, all served from the same group of source files.

Publishing is as simple as a right-click and selecting the Publish command from the menu.  You can publish one topic, a chapter, a book, or a whole project in just one click. No more time consuming, complicated build scripts or having to upload files to a web server.

Using HelpServer

Now that we had our legacy content imported, we were ready to get down to serious work. At Voxeo, we have technical communicators in Germany and the USA. The ability to work on the same project across geographical boundaries was a necessity. HelpServer automatically enables a technical communicator to checkout and lock editing from other technical communicators.

In the HelpServer Workbench client, you can open a topic in a basic WSYIWIG editor.  The editor's toolbar contains familiar Microsoft Word‑style icons and commands shown in Figure 2.

Figure 2: HelpServer workbench editor

While the Mac OS X provides spell checking, HelpServer has a fully customizable spell check solution with custom word dictionaries, auto correction, and contextual word suggestions.

The search and replace feature is highly customizable by content, topic statuses such as modification date or author, feedback, for example, topics with ratings of 2 or less, by language, and much more. The search can be set to within the current topic, chapter, or project, or all projects. This feature is very useful when changes need to be made across an entire documentation set.

Customizing the look

A key feature of HelpServer is the capability to customize the authoring Workbench, as well as the web page layout of the content for the end-user. We are not web page designers; yet building a content portal is simple and customizable enough to easily suit our needs. By using schemas and styles, we can change, update and publish our entire customer-facing content portal in just a few clicks of a mouse, or setting properties for each object, shown in Figure 3.

Figure 3: Project properties

Different schemes can be applied to different projects for both web and print. On the front-end web view, you can add or remove buttons, toolbars, organization logos, background graphics, and much more. You can even override the scheme for unique settings at the individual topic, chapter, or project level.

It is easy to create custom style sets that you can apply to content at the topic, book, or project level. You can add a Print style set to format headers, footers, table of contents, leading and trailing pages, and indexes as well.

Features we really like

HelpServer is feature-packed and we could write 20 pages and still not cover them all, so we will just describe our favorites.

Search Engine Optimisation – At Voxeo, we rely on search engines to direct customers to our organization's site. HelpServer content can be crawled by search engine spiders and indexed. You can create your own URL for each project, chapter and topic by assigning aliases and pointers as shown in Figure 4.

 

Figure 4: Alias and Pointer Settings

Search Customization – Each user can customize search preferences with advanced search options.

 

Resolving Links – Since topics are object references, no matter where you move a topic, the link to that topic is always valid.

 

Print to .PDF – HelpServer creates on-the-fly .pdf format files for topics, chapter, books, or entire projects with just one button click. The .pdf file is created dynamically to always reflect the latest changes.

 

Feedback and Notification – Our users can enter feedback for any content. As soon as the user saves the feedback, the HelpServer notification system creates an email message alert so we can respond right away.

 

Annotations – Sometimes we need to make a note about an item in a topic. With annotations, we can insert comments into the topic that are only seen internally. This is particularly useful for editing and follow up.

 

Snippets - We re-use text throughout our documentation set using snippets. As we type, a snippet can be inserted for the text we use again and again. This keeps consistency in our documentation and will help reduce costs for translation.

 

Glossary Terms – In our business, we use a lot of technical jargon. With automated Glossary Terms, a simple right-click and select Generate Glossary Term Links adds links to matching entries in your glossary.

 

Security - Using authentication in Workbench, an administration can limit author, editor, and user access to HelpServer content and authoring capability by group or individual user.

 

Export – We can easily export HelpServer content to static HTML, .pdf, .chm as well as to HelpServer exportable projects.

 

Language – Right now, Voxeo only offers English documentation, but HelpServer dynamically supports multi-language content, as well as support for translation agencies using export and import. In addition, the Workbench user interface can be configured to use a variety of international languages.

 

Other features

HelpServer is highly customizable on the back-end and front-end. As such, we just haven't had a chance to check out everything, but we couldn't resist mentioning these other great features we haven't even used yet.

Workflow – Structured task assignment and tracking for the creation of a topic from start to publication.

 

Metadata – Ability to add and search on data about the content that it is attached to. For example, who the author is, the audience the topic is intended for, topic type, etc.

 

Auditing – User and author event logging for documentation and system additions, changes, or deletions.

 

HelpServer Assist – A dynamic Help pane providing contextual topic suggestions as a user navigates the documentation set.

 

There are too many more features to mention. For more information, see www.helpserver.eu .

Our experience

As with any Content Management System, there is a learning curve. At first, importing, creating, and editing went slowly. However, combining the comprehensive online HelpServer documentation, our on-site training, trial environment, and superb HelpServer support, we were up and running public-facing content in less than a week.

HelpServer is just plain easy to use, highly customizable, a great value, and presents a professional image as a documentation platform. Voxeo documentation has never looked better.

The bottom line

We haven't yet explored all aspects of our HelpServer implementation, but what we have seen so far is pleasantly surprising and leaves us very optimistic about the future of our documentation program.

As our organization scales in growth, HelpServer will scale right along with us.

References

Voxeo Corporation - www.voxeo.com

Voxeo Documentation - help.voxeo.com

4.ST – HelpServer - www.helpserver.eu

About this HelpServer product review

This HelpServer product review titled "Using and implementing HelpServer" was written by James 'Van' Vanslette and  appeared in the 2012 Summer edition of Communicator, you can view the original product review here. Communicator is the authoritative, award winning, journal for UK technical communicators.  Communicator is home to high quality, objective, and peer-reviewed, current, relevant, and in-depth articles. Communicator is free to ISTC Members.

About the author

James 'Van' Vanslette is a seasoned technical writer and documentation manager. After 24 years of technical writing in the United States Air Force, Van went on to Microsoft as a programming writer. Eight years later, he became the documentation manager at Voxeo in Orlando, Florida. 

E-mail:

 

Information provided by Voxeo - June 201