Review of AuthorIT V4

By Matthew Ellison

Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

• Introduction to AuthorIT
• Key Concepts
• Using the Tool
• Importing External Documents
• Publishing Output
• Workgroup Support
• Online Help
• Summary

Introduction to AuthorIT    

AuthorIT sets out to be more than just a Help Authoring Tool—in a nutshell, it is an authoring tool that enables you to create Word documents and various forms of online assistance from a single source. It’s true that there are a number of other tools on the market that claim to do this—but most of those are based on the paradigm of authoring for one medium (either print or online), and then converting the content to the other required formats. AuthorIT is different: it stores content in a database in an “output-neutral” format—from there it can be output to HTML, and the format and content can be customized for each of the various output options.

AuthorIT is developed by New Zealand-based AuthorIT Software Corporation. A comparative newcomer to the Help authoring market, AuthorIT was originally released in 1997, but has only been marketed in the US and Europe since 2000. Since then it has attracted a considerable amount of interest, particularly from content management practitioners (it is one of a select list of nine content management tools referenced within JoAnn Hackos’s 2002 book Content Management for Dynamic Web Delivery).

Key Concepts     

Object-Oriented Approach

One of the things that distinguishes AuthorIT from other Help Authoring Tools is its object-oriented approach. Every aspect of the content that you create is represented as an object—these objects are building blocks from which you can assemble other objects, which ultimately you combine to create a "book"—a book is AuthorIT’s term for a self-contained collection of information that may be output (published) as a manual or as a Help file.

For example: you may create a new Topic object by writing several paragraphs of text (each of which has a Style object associated with it) and inserting a screenshot (which is represented within AuthorIT as a File object). This topic is also associated with one or more Media objects that determine the page layout of the document output, the window design of the WinHelp output, and the page properties of the HTML-based output. Finally, any links that you create within the topic are themselves saved as Hypertext Link objects.

AuthorIT stores all the objects that you work with in a database, which it calls a Library. When new to AuthorIT, it is easy to make the wrong assumption that a library corresponds to the notion of a project in other tools—in fact, a library is a much broader collection of information, and can contain many books. The advantage of having many books within the same library is that they can share objects—for example, a topic that appears within an online Help system could also be part of another book that is used to publish a training manual. In this case, any changes made to the content of the topic object would be automatically reflected in both the Help system and the training manual.

Object Templates

Objects have properties, some of which are specific to a particular output format (Word document, WinHelp, and HTML-based output). For example, topic objects have an “Include in Browse Sequence” property which is applicable only to WinHelp output.

WinHelp-specific properties for the "print reports" topic

To save you the trouble of having to set all these properties each time you create a new object, AuthorIT provides a set of Template Objects on which you can base your new objects. Any new object inherits the properties from the template on which it is based, and remains associated with that template. As well as being a time saver, this system of templates also ensures a degree of uniformity and consistency throughout all books within the same library. Furthermore, it is easy to make global changes throughout a library by making changes to a template—these changes ripple through to any object associated with that template.

I have a slight problem with the way in which the template objects are listed within AuthorIT, which is that many of the different types of object template share the name of "Normal". This means that, until you are very familiar with the system of icons that AuthorIT uses to represent each type of object, it is very difficult to distinguish between the different templates.

List of Normal templates

Output-Neutral Database

AuthorIT stores content in its database as images or pieces of text, and with a style name associated with each. It does not represent the content using any kind of markup language or formatting syntax (such as HTML, RTF, or Word) and so it is totally neutral with respect to the various formats in which it might ultimately be published. This can be viewed as either an advantage or a disadvantage: looking at it from a positive point of view, the author is less likely to develop content in a way that favors any specific output medium, which increases the likelihood of success across the full range of output formats. On the other hand, since the author does not have access to the underlying code of the output format prior to publishing, it makes it difficult to exploit advanced techniques such as scripting and DHTML.

Styles-Driven Formatting

Unlike other tools, AuthorIT does not allow authors to apply their own "inline" character and paragraph formatting. Instead, all formatting must be applied by choosing from the list of pre-defined character or paragraph styles. Some authors might complain that this suppresses their creativity, but is has the effect of ensuring that all content has a consistent look-and-feel, no matter who creates it. It also enhances the ease of maintenance by ensuring that global changes to formatting throughout an entire library can be made easily by changing one of the styles.

The actual formats associated with each style are examples of output–specific properties (described above in the section on Object Templates). Each style actually has four sets of formatting properties, which are independent of each other:

• The Style Definition tab (shown below) defines how the style will be represented on screen in the AuthorIT text editor, and has no effect on any of the possible outputs.

  

• The Windows Help tab (shown below) defines how the content will look when published to WinHelp.

  

• The HTML tab (shown below) defines how the content will look when published to any of the HTML-based formats (including HTML Help). The formatting for HTML is actually written into an external style sheet (stylesheet.css) to which AuthorIT automatically links all the pages that it creates.

  

• The formatting for each style in the Word document output is defined within a Word document template. In order to change the format of a style in the document output, you have to do this outside of the AuthorIT environment by opening the Word document template and making the change using Word.

AuthorIT’s style definitions are stored within a restricted area of each library, and only those authors with the appropriate privileges are allowed to edit, delete, or add to them.

Conditional Content

AuthorIT enables you to specify for each object whether it should be included or excluded in each of the three types of output (Word document, WinHelp, HTML-based Help). In practice, this setting is usually inherited from the template on which you base each new object that you create, though it is possible to clear this setting within the template so that it can be set on an object-by-object basis.

The "Include object in" options—blue text indicate properties inherited from template

The most useful application of this is the ability to include or exclude specific paragraph styles from the output—although it is not explained clearly within the online Help, this enables you to implement a system of conditional text. You do this by creating a new character style (which might have the same formatting properties as default paragraph text), and then applying it to any text that you wish to be conditional. By checking or unchecking the "Include object in" check box for the particular output that you are publishing to, you can then include or exclude the style (and hence also the text to which it has been applied) from your output. Although this means that conditional text is technically supported down to the character level, it is not quite as intuitive a system as I have seen in other tools.

There are instances where you might wish to be able to include or exclude entire topics, depending on the output required. For example, if you were writing Help for an application that can be used on both a Windows PC and a Mac, then there might be some topics that are specific to either of the operating systems. Instead of using the strategy described in the previous paragraph, AuthorIT’s object-oriented approach makes it possible to create two separate books without adding to the maintenance overhead. Although core topics that apply to both operating systems would appear in both books, they would in fact be held in the library as a single topic object, and would have to be updated in only one place.

One final aspect of AuthorIT that is especially powerful is the ability to embed topics within other topics. This means that it is possible to write core pieces of content once, and then embed them in multiple topics where that information is required. I have found while using the product that this offers many useful opportunities for re-using information and hence reducing maintenance.

Gray shading indicates embedded topic

Designing the Output

I’ve already described how AuthorIT enables you to assign different formats to your styles for each of the various output types. But AuthorIT also gives you control over many other aspects of the final presentation, including pagination, margins, windowing, and cross-references.

AuthorIT’s ability to insert cross-references automatically is especially interesting. For example, it is a simple task to specify that each chapter of your Word document output will commence with a mini table of contents that lists all the sections within the chapter, and the page number for each one. These links are not actually contained within the source topic objects—they are inserted automatically by AuthorIT at publishing time, based on the relationships between topics in the table of contents. You control this by setting properties in the topic object, where you can define groups of links to related topics (in this example, child topics). You can also specify which output formats these links should be included in, and in what position within the topic the links should appear.

Topic object—Related Topics tab

In my view, these automatic cross-references are somewhat over-used in the online Help for AuthorIT itself, where every "section" topic has a set of links to all its child topics (beneath the heading of "In this Section") as well as a set of links to all its sibling topics (beneath the heading of "See Also"). I would have preferred the cross-references to be more selective, and perhaps to be based on shared index keywords rather than relationships within the table of contents.

Example of automatic cross-references within the Help for AuthorIT

Using the Tool     

First Fmpressions

My first impressions on using the tool were that it is unlike any other Help authoring tool that I have used. Indeed, in some ways, being rooted in the paradigm of another authoring tool is a disadvantage, since some of the fundamental concepts of AuthorIT are so radically different that it takes a while to adjust to a new set of ground rules. An example that has already been mentioned is the concept of a library, which contains a pool of objects that can be grouped in various different ways to form the required books.

Stability

While I was testing AuthorIT V4, I imported and worked with a number of fairly substantial document sets, and accrued several hundred topics within my library. There were occasions when the tool reported an error and exited prematurely—however, these were relatively infrequent, and the overall integrity of my library was never compromised. This is a very important issue for tools that rely on a database—I remember more than one in the past having to abandon a ForeHelp project and return to an earlier backup because the database had become irretrievably corrupted.

I did come across a number of small technical issues: for example, the Import Module sometimes misreads the filenames from the [Files] section of an HTML Help project file, and only imports topic files correctly if they are listed within the .hhc file. However, AuthorIT support was very responsive, and assured me that such bugs would be corrected. When they become available, fixes can be download for free from the AuthorIT web site.

User Interface

AuthorIT’s radical and unique approach extends to its user interface, which can seem very daunting on first use. This is partly due to the proliferation of objects—since each element of a book (index entry, image, topic, etc.) is represented as a separate object, the number of objects that make up a book is typically about 5-10 times the number of topics. This means that a Help system with a mere 100 topics will be composed of up to 1000 separate objects. Typically, these objects are displayed together within the same window, though it is possible (but not imperative) to sort different types of objects into separate folders.

Another aspect of AuthorIT’s interface that takes some getting used to is the multiplicity of windows that you can have open simultaneously. Each time you open an object to examine or edit its properties, a new window is opened. And there is no need to close one object before opening another. This means that, unless you are reasonably careful, the number of windows open on your desktop can become unmanageable and confusing.

Having said that, some of AuthorIT’s functionality relies on having more than one window open at a time. For example, the only way to assign an index entry to a topic is to drag the topic from the main AuthorIT Window (or from a book window) into the window for the index entry object. Note that you are actually assigning the topic to the index entry, which makes sense when looking at the relationship from a user’s perspective.

One potential area of confusion is that, when a new window opens, the menus in all other AuthorIT window gray out. You might assume from this that they are no longer available—but this is not necessarily the case. It simply means that the window to which they belong is currently out of focus. It is occasionally necessary to choose an option from a grayed out menu—for example, when you need to publish a book that is open, the Publish menu in the Main AuthorIT window is grayed out. However, when you click on it, it makes the "Publish To" option available. I believe this is a design wrinkle that should be ironed out.

Navigation

As an author, finding your way around the topics within a book is actually quite easy since all the topics are organized within the book in the same expanding/collapsing table of contents that the user will see when you publish to online Help.

The proliferation of objects mentioned in the last section actually does not seem to matter from a navigational point of view. This is because you will normally be starting from a topic object when you decide you need to access another type of object, and AuthorIT makes it very easy to find objects that have any kind of connection with the current topic. It enables you to display a list of either:

• the objects that are used by the topic (shown below)—for example, all styles and images within the topic, and the template on which the topic is based,

  

• or the objects that use the topic (shown below)—for example, all links that target the topic, and all index entries to which the topic has been assigned (remember that topics are assigned to index entries, not the other way round).

  

Having displayed the list of objects, you can then double-click on any of the objects in the list to display and/or edit its properties.

Text Editor

AuthorIT's Text Editor

AuthorIT’s inbuilt Text Editor is simple and straightforward to use. Since it has been designed with the needs of technical authors in mind, it contains many useful shortcuts (such as buttons for assigning a range of commonly used styles) and is not bloated by numerous features of Microsoft Word that are seldom (if ever) required by authors of technical manuals and online Help.

I was pleased to find that it supports one of my favorite keyboard shortcuts from Microsoft Word: Ctrl+Spacebar for removing character styles. However, one small gripe is that it is not possible to specify a "Style for following paragraph" within a style definition as you can in Microsoft Word. This means that, if you type apply a Heading 2 style to a piece of heading text and then press Enter, you invariably then have to change the style of the new paragraph from Heading 2 to Body Text.

A powerful Find and Replace facility enables you to target text within a range of different levels, from the selected text only, right up to the entire library. There is also very rich support for tables.

Importing External Documents     

Importing legacy content is one of AuthorIT’s real strengths, and it can convert from a range of different formats including Word documents, FrameMaker documents, HTML Help projects, WinHelp projects, and plain HTML pages. To an extent however, it does rely on the source information conforming to a somewhat restrictive set of conventions—any Word documents that use outlandish formatting, such as excessive use of text boxes, can cause rather unpredictable results in AuthorIT. This means that it may be necessary to do some rationalization of the document in Word before importing it into AuthorIT.

If you import some content and then immediately output it from AuthorIT to exactly the same format as it was originally in, you should not expect necessarily to end up with exactly the same as what you started with. In other words, AuthorIT is not guaranteed to "round-trip" all formats perfectly. In some respects, you may find that AuthorIT has actually enhanced the content and presentation by adding supplementary cross-reference links and rationalizing the formatting. However, in the case of imported HTML, certain elements of the original content may disappear altogether—these include scripts, HTML Help objects (such as Related Topics and ALinks), and pop-up links.

If you import an HTML Help project that contains some topics that are not in the table of contents, and then you publish to HTML Help output, you will notice that the hidden topics have been mysteriously restored to the table of contents within a placeholder entitled "Non-TOC Topics". However, it is possible to remove them again by unchecking the "Do not show in contents" property on the Windows Help tab for each of the topic objects—this property applies to HTML Help as well as WinHelp (thank you to Char James-Tanny for that tip).

Having just described some of the issues to look out for, it is important to emphasize that AuthorIT is really very good at importing existing content. Its Import Module does an excellent job of mapping styles and formats to AuthorIT’s own styles. Remember that AuthorIT does not permit inline formatting (that is, formatting without the use of a style)—when it imports, it does as good a job as it can to recognize any important inline formatting and map it to the appropriate style. You can improve the efficiency of this process by writing your own rules, for example to detect all text that is red and bold, and apply an AuthorIT style of Warning. The following screenshot shows how you would achieve this:

Rule for mapping bold red text to the Warning style

Publishing Output     

AuthorIT is capable of publishing to a wide range of different formats, including Word documents, WinHelp, HTML Help, and browser-based Help. As mentioned already in this review, the ability to customize content and style objects for each of these different outputs gives a high degree of control over the presentation.

AuthorIT takes the approach of using "lowest common denominator" technology for the deployment of content. For example, for the HTML Help output, it uses no dynamic HTML, JavaScript, Java, ActiveX, or HTML Help controls other than for the table of contents and index. However, it still achieves rich navigation support by being able to insert regular hyperlinks automatically, based on the relationships between topics. So where you might have previously used ALinks to provide links within groups of topics, AuthorIT enables you to specify that each topic should automatically contain a "See also" link to each of its siblings. This does not necessarily provide you with the flexibility that you need for inserting specific cross-reference links from certain topics—after all, the most useful information is sometimes to be found in a totally separate area of the table of contents.

AuthorIT’s deliberately low-tech strategy extends to its browser-based HTML and XHTML outputs. Instead of using "browser sniffing" scripts to adapt its pages to work in the various browsers, AuthorIT sticks strictly to the W3C standards (HTML 4.01 +CSS and XHTML 1.0 + CSS respectively) and does not use any scripting at all. Thus, the expanding and collapsing table of contents is represented by several HTML pages, each of which shows a different section of the table of contents open. This may seem a rather heavy handed approach, but it has the advantage that it is guaranteed to run on any user’s browser, even if both Java and JavaScript are disabled.

HTML Table of Contents

AuthorIT has a batch publishing tool that makes it easy to publish to all the formats that you need from multiple books in a single operation. This is very useful, since it can take several minutes to publish even a single output from a very large book. It means that you can set the batch publisher to work overnight, and return in the morning to find all published versions of your books ready and waiting.

Batch publishing window

Workgroup Support     

AuthorIT is available in three different editions, Desktop, Workgroup, and Enterprise. While the Desktop edition is designed to be used by a single author, the other two editions add a number of multi-user features including version control, and dynamic check-in and check-out.

I did not have the opportunity to test fully the workgroup features in version 4. However, workgroup support is one of the tool’s key aspects, and could well be the most compelling reason for many authoring teams to consider using it. Its object-oriented approach allows for multiple objects within the same library to be worked on independently and simultaneously by different authors. Dynamic check-in and check-out prevent two authors from working on the same object at the same time. This means that, while you might have been forced into adopting a modular Help system to support team-authoring with other tools, AuthorIT allows multiple authors to collaborate on a single Help file. This makes it easier to create a seamless and consistent Help system, and in particular is likely to improve the quality of the combined index.

I am impressed with AuthorIT’s sophisticated security system. This allows individual authors to access only the objects that they need, and prevents key objects such as templates and styles being arbitrarily changed.

Online Help     

I am always interested in looking at the online Help that accompanies tools for creating Help. In the early stages of using this new version, I had many questions and turned to the Help quite frequently. I found that the Help looks polished and professional, and is very comprehensive in terms of covering every aspect of the tool. The fundamental principles of the product, which can be quite challenging to novice users, are clearly explained and illustrated.

However, I did find the Help rather oriented towards conceptual and reference information—after reading about a feature, I would sometimes be left with the question, "That’s all very well, but how do I actually use it?" I also found the index to be missing many of the user-focused tasks and phrases that I was seeking.

I have one other gripe relating to the Help: except for the Help menu in the main AuthorIT window, there are no visible access points for Help within the user interface. OK, it is possible to display context-sensitive Help for each window by pressing F1—but I don’t believe that even Help authors should be left with F1 as the only means of accessing assistance. A Help button placed wherever online Help is available would be more intuitive, and probably more frequently used, in my view.

Summary     

It is difficult to compare AuthorIT directly with any other tool, since it breaks the mold and cannot be classified simply as a Help authoring or documentation development tool. It is an ambitious product that provides a one-stop shop for content authoring, conversion, content management, version control, publishing, and project management. If you have a need for all these facilities, then AuthorIT is a compelling option—particularly if you have a team-authoring environment. The fact that the team only has one tool to master in order to be able to do all these things could pay dividends in the long term—however, you will need to be prepared for an extensive period of setup, familiarization and training, due to the highly complex and distinctive nature of the product.

My view of the key strengths and weaknesses are as follows:

Key Strengths

• Object-oriented environment provides unlimited scope for conditional content and information re-use
• Independent customization for different output types makes single-sourcing a truly viable proposition
• Strong workgroup support
• Excellent import module that provides rich mapping capabilities
• HTML and XHTML outputs support all version 4+ browsers

Key Weaknesses

• Complex user interface makes for a steep learning curve, and the database-authoring paradigm may not suit all authors
• Relatively short track record in the market
• Author has restricted control over underlying code of HTML output, meaning that scripting opportunities are limited
• Lack of support for dynamic links (ALinks)
• Extent of robustness and stability of code is not yet fully proven.

For more information about AuthorIT V4 visit the AuthorIT web site.

Matthew Ellison has 18 years experience as a user assistance professional in the software industry. He has been a popular speaker at WritersUA events throughout the world since 1997, and now runs his own independent UK-based training and consulting company specializing in online Help design and technology. Matthew holds a B.Sc. in Electronic Engineering and a Post-Graduate Certificate of Education from Bristol University in the UK. He is also a certified instructor for a range of Help Authoring Tools.