Author-it and MadCap Flare comparison

I’ve had more than a few questions asking for a review of Author-it or MadCap Flare or a comparison of both. So I decided to do some homework. Initially, I wasn’t sure why they are categorized together. Is it due to the price point? Or is it due to the single-sourcing all-in-one software package aspect? I suspect it’s the latter since the former seems more disparate lately.

Let’s examine the single-sourcing aspects.

Both MadCap Flare and Author-it only work on Windows for authoring (but both offer cross-platform and cross-browser output).

Both MadCap Flare and Author-it output to printed and online formats. These formats and the way they arrive at the output offer some differences, as seen in the “publishing aspects” section below.

Both MadCap Flare and Author-it have a single place to store source.

Both are sourced in databases. The single source for MadCap Flare is in a flat folder structure with XML files.  MySQL database. The single source for Author-it is in either a free Jet/MSDE/SQL Express database for up to 4 MGB of content, or SQL Server.

Author-it only imports Word documents. Flare imports both Word and FrameMaker documents as projects.

What are the publishing aspects?

Author-it uses Word templates for all printed page layout. If you’re well-versed and experienced in Word for page layout, this product works for you.

Author-it uses CSS for HTML layout, but some layout and graphics are controlled in different areas. I had to uncover the locations for each graphic and CSS area recently while customizing the HTML output for the One Laptop Per Child project. In my experience the HTML layout was all over the place. From templates to stored objects to files stored locally to certain aspects changed within a dialog box on a template, I felt like the online layout was a bit scattered.

Here are links to their Knowledge Center articles that were helpful: Customizing Related Topics in HTML, Adding a Customized HTML Template, and Using a Customized HTML Frameset. I muddled through somehow, and I don’t have a good comparison for MadCap Flare’s HTML output.

Keith Soltys has a nice Review of MadCap Flare from summer of 2007 that shed some light onto the publishing and he speaks highly of the layout rendering nicely in both FireFox and Internet Explorer. It’s interesting, though, that he’s evaluating Author-it as well, so I guess these two products are often compared side-by-side.

Apparently MadCap Flare uses CSS for all layout aspects including print. The new Blaze announcement offers a non-Frame and non-Word reliance for actual PDF or print output. The reliance on CSS (Word’s interpretation of CSS has its limits) may have forced MadCap to create Blaze. Anyone else think you should wait for the CSS 3.0 specification before really nit-picky print layouts can be accomplished? Or is CSS ready for this level of design? I know with the OLPC project, we’d love CSS layout for really nice ebooks, so maybe MadCap is onto something with CSS for print layout.

I’ve written up this comparison because many people have asked me for it, but I know it’s lacking. Please, feel free to fill in the gaps that this post has so that others may fairly evaluate each tool in their environment.

I had an email conversation with Kai many months ago, who was a good sport with all of my questions regarding the content and priorities with that content. He realized, though, that Author-it was probably eliminated due to its use of SQL Server – they wanted a MySQL database container for their content. So I figured that MadCap was their final answer. It is so interesting how the final decision can be dictated by the underlying system requirements. One of the commenters on Gordon Mclean’s post, Why AuthorIT? (sic, they’re now Author-it) was seeking a similar authoring tool but on a Mac platform.

Sorry Kai for dropping the conversation for so long. But please do share your experience with the tools since then.

Subscribe to the comments for this post

Author-it Table Of Contents expansion

My co-worker Melissa Burpo (yep, I interviewed her before she was my co-worker) has solved a nagging problem with the HTML output from Author-it. The Table of Contents would always lose your place when you expanded one of the TOC items – instead of “keeping your place” vertically, it scrolls your view to the top of the frame. We have a long table of contents and this particular implementation got a lot of complaints.

Rather than shorten our Table of Contents (I would guess that’s what most shops have done), Melissa used Javascript to capture the scroll location, save the location using a cookie, and then reload the scroll location after you expand or contract the Table of Contents.

She’s allowing me to publish her solution here – let us know if you find it useful! You can see it in action at docs.imis.com.

Inserting code into your Author-it Table of Contents

Download the toc_scroll.js file supplied here and save it to your HTML Templates directory, such as C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML\.

Open the toc_template.htm file supplied with your Author-it installation in C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML\.

In the <head> area, insert a pointer to the toc_scroll.js file using this code:

In the next few lines of the toc_template.htm file, give the starting point for the scrolling to load.

Modify your book so that it includes the new toc_scroll.js file and the new toc_template.htm file.

Publish your book using these modifications.

We’ve tried it on Windows XP and Vista, IE 7 and 6 and Firefox 2 and 3. Let us know your thoughts on this “fix” for a scrolling annoyance, and if you use it, give a hollah!

Subscribe to the comments for this post

Understanding the database implementation of Author-it

Author-it uses a SQL Server database to house all of the source material that make up your deliverables. You can export that database content to XML and publish to Word or HTML and other outputs, but the source is stored in a database.

For locally-run databases (meaning that Author-it and the database are on the same computer), you can use a Jet database (also known as Jet, or MSDE, or SQL Express) to store your content. Updated to add: With a Jet database, your content cannot 2 GB and the upper limit for users is 5.

For server database installations, where the content is stored on a separate database server, you can use SQL Server 7.0, SQL Server 2000, or SQL Server 2005. You can use a pre-existing SQL Server database such as one that your company uses already by simply asking for a database to be created with certain permissions already set. That configuration is what we do at ASI.

You can also install and run your own SQL Server database using SQL Express which is relatively painless to set up and the installation instructions from both Author-it and Microsoft are detailed and thorough. The limitation for this configuration is that your Author-it library cannot exceed 4 GBMB.

Here are some helpful links for researching the database aspect of Author-it:

Installing Author-it

System Requirements for Author-it

Subscribe to the comments for this post

Publish a Word outline using Author-it

At ASI, we’re working on book skeletons while we do task analysis for new documentation or feature updates that may change the way users do their work with iMIS. So, to get early feedback, we wanted a way to publish an outline of that skeleton book with no page numbers, but headings and subheading levels indicated clearly.

My first attempt at a macro called within the AfterPublish macro gave me the inverse of what I wanted (content but no outline), but my coworker Mary Connor, being the VBA expert that she is, came up with a working macro. It basically says, if you’re a section break after the 2nd section break, throw that content away but keep the table of contents content.

Here is an overview of the steps to get an outline out of a book made in Author-it.

These are pre-requisites to the publishing step:

In Author-it, create a six-level TOC object that doesn’t contain page numbers. Six was the number of levels we thought was an extreme case, and you can’t go higher than six levels of heading in HTML anyway, so six seems like a good number for us. Your situation may vary.

In the .dot file that contains your AfterPublish macros, create a TrimToOutline macro that contains this code:

Sub TrimToOutline()
'
' Freezes table of contents field, then strips off everything after the contents:
' Macro recorded 6/26/2008 by Mary Connor
Dim dSection As Section
Selection.WholeStory
Selection.Fields.Unlink
For Each dSection In ActiveDocument.Sections
If dSection.Index > 2 Then
dSection.Range.Delete
End If
Next
End Sub

In the Sub AfterPublish() area of your Word template file, put a call to TrimToOutline.

In Author-it, create a new book template for outlines, and point it to the .dot file that contains that macro code above.

Next are the steps for publishing your sub-book content to a Word outline-only document. It’s not actually in the Word outline view, but rather, a table of contents without page numbers, but based on the skeleton sub-books placed within the book you’ll create below.

1. In Author-it, create a book using the outline book template that you created previously.
2. Drag any sub-books into this new book and save the new book.
3. Publish to Word.
   The resulting Word document should contain only a title page and a table of contents.

I’d love to hear feedback or ideas for improving this specialized output for Author-it, so please feel free to comment.

Subscribe to the comments for this post

Adding Google Analytics to your Author-it generated HTML pages

I’m learning about Author-it’s HTML templates today, and how to insert Google Analytics code (or any other code, really, such as adding an automatically updating variable for “Last modified by” with user or date information.)

But my task today was to insert Google Analytics code. (As a prerequisite note, we already have all our documentation available on an external site at docs.imis.com.)

First, I created a Gmail account for our department. Next, I created a Google account. Then, I went to the Google Analytics page and signed up for an account there, entering the name of our externally-accessible documentation site.

At the end of the sign up process, Google gives you javascript code that you want to place directly above the closing body tag </body>. Fortunately, the way that Author-it sets up the HTML templates, all of your Author-it topic data is inserted at a point where the <aitdata> tag appears in your HTML template.

The HTML templates are typically stored in C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML, although other types of HTML templates such as DHTML and HTML Help templates are also available. These are the files I discovered that Google Analytics needed to be installed on.

• I edited the body_template.htm file and located the <aitdata> tag. I copied the code from the Google Analytics page and pasted it below the <aitdata> tag.
• I edited the html_frameset.htm file and added the Google Analytics code in the <head> area as instructed by the Google Analytics help, which, as a side note, has a set of completely question-based articles, as in, all headings are written as a question. Fascinating. The topic is “What should I know about using Analytics with Framed sites?“

Now, republish the HTML from your Author-it topics and your Google Analytics code is available on each page. After about 24 hours we started collecting data.

Let me know your experiences using Google Analytics to monitor your user assistance site traffic – what metrics are you seeking? Are there any conversion goals we should set up? One metric I am considering is trying to monitor how often the Word .doc files are downloaded. Does anyone have tips or tricks for us?

Update: I found this blog entry, Tracking document downloads in Google Analytics, and it contains hints at what I need to do to track our Word document downloads. However, I think that this article from the Google Analytics Help, How do I track files (PDF, AVI, or WMV) that are downloaded from my site? contains the method I’ll try first.

Subscribe to the comments for this post

Author-it and converting UTF-16 to UTF-8

In trying to modify multiple Author-it topics (okay, 5,119 topics) with variable assignments, I have had to work with the XML output that Author-it exports.

To export to XML, you select a topic or multi-select topics, then right-click on the selection and choose XML > Save to file.

Turns out, Author-it outputs its XML encoded with UTF-16, but apparently most Windows applications understand UTF-8. When I tried to open my freshly export XML file, XML Copy Editor gave me an error.

So I had to discover how to convert the XML from UTF-16 encoding to UTF-8 (and you can’t just open it in Notepad on Windows and change the 16 to 8, there are other embedded characters indicating the encoding, and, well, it’s encoded.)

First, I used the identity transform documented many places, my favorite place being the XSLT Cookbook, to convert the Author-it output to UTF-8. Here’s the XSLT code for that:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output encoding="utf-8"/> <xsl:template match="@*|node()">

	<xsl:copy>	 	<xsl:apply-templates select="@*|node()"/>

	</xsl:copy> </xsl:template>

</xsl:stylesheet>

I just ran the above transform against the AuthorIT Objects.xml file I exported, using the Instant Saxon XSLT processor.

Then, I wanted to remove all <VariableAssigments> elements, effectively removing an entire node. Again, the identity transform (or copy transform) was effective. And, I learned that I had to identify the AuthorIT namespace thanks to this excellent helper article, Handling Default Namespaces on topxml.com.

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

xmlns:ait ="http://www.authorit.com/xml/authorit">

<!--Match everything using identity copy-->

<xsl:template match="@*|node()">

	<xsl:copy>

	<xsl:apply-templates select="@*|node()"/>

	</xsl:copy>

</xsl:template>

<!--Remove all the VariableAssignment nodes-->

<xsl:template match="ait:VariableAssignment">

	<xsl:comment>Removed VariableAssignment element</xsl:comment>

</xsl:template>

</xsl:stylesheet>

This transform is pretty dangerous, though, because it’s taking away all the VariableAssignment elements, and you might have valuable metadata stored that you would quickly blow away. So use with care.

This workaround is likely also useful for DITA and XHTML files, because Author-it outputs its DITA and XHTML files as UTF-16. I haven’t investigated its usefulness for those areas, but a quick search on the Author-it-users group on Yahoo revealed that sometimes people want UTF-8 rather than UTF-16. So, I hope this helps.

Subscribe to the comments for this post

Author-it webinar on version 5.0

Our team is so excited for the new Author-it version 5.0 that we invited other Austin techpubs teams over to our office to watch the US & Canada webinar. It was like a movie premiere. Okay, we’re not really that big of dorks. But we had a good time with it.

By my calculations, it was about four AM Australia time but both the presenters were troopers, even when the typed-in license key didn’t “take” during the migration portion of the demo. All of us in the room empathized with her and she smoothly avoided any delays.

I’m mostly excited about the new interface. And Australians New Zealanders say “ribbon bar” so sweetly. It’s such a nice update. I’m really looking forward to using it. The organization of styles and templates makes sense as well, and I am glad to have separation between paragraph styles and character styles.

The search bulk-ups contain the features my co-worker was looking for – search within a folder and match case or whole word. Also the search within a topic as a customizable panel pop-out is going to be highly useful. That new editor interface is especially exciting. It reminds me of XMetal’s editing environment.

We can’t wait to start trying publishing profiles. We wanted to just start clicking in the dialog boxes displayed during the demo. Their knowledge base says that eleven profiles are shipped right out of the box (mapped directly to publishing outputs). The output types I see in version 4.5 are DITA, Word, PDF, HTML, XHTML, HTML Help, Microsoft Windows Help (RTF-based), Java Help, Oracle Help, XML, and Author-it Website Manager format. Since that list adds up to eleven types, I guess there are no new outputs with this release.

While we don’t currently have a use for Author-it Xtend, I found it fascinating as a concept. Why would a techpubs department pay money to a vendor for an embedded search engine to try to encourage writers to re-use? Why not just spend that money in training (or hiring) writers to think more about topic orientation and re-usability?

My co-worker pointed out that in a translation situation, Xtend might pay for itself in one translation round. It seems so very Google-like. There’s this sliding bar for more Fuzzy matches and more Relevant matches. There’s color coding for matches. I’m automatically drawn to it like a moth to a back porch light, yet I’m not sure of the best applications for the search hits nor what problem teams should expect to solve with this functionality. Perhaps someone can tell me the best scenarios for this add-on?

We copied the Questions and Answers from the webinar, and people asked plenty of questions. Here’s just a sampling – does 5.0 run on SQL Server 2005 (yes), does it run on Windows Vista (yes), questions about the new Project Manager (purchased as a separate module but is integrated into 5.0), is the 5.0 upgrade covered by a maintenance contract (yes), can you upgrade from 4.3 to 5.0? (yes), are presentations part of 5.0 (yes), and the final question was a good comparison: Can I use the Filters (Variables) on the Publishing Profiles as I would have used conditional build tags in RoboHelp to include/exclude content from specific output types? Am I understanding this correctly? The answer: yes, that’s correct.

So, exciting new features abound and we can’t wait to get our hands on them. I’ll keep you posted on our progress.

Subscribe to the comments for this post

Author IT – boldly climbing the learning curve

I thought I’d continue posting about my experience with Author IT since my initial review of AuthorIT. This past month I’ve been exploring ways to help out with the Author IT nuts and bolts, doing maintenance-type and infrastructure tasks such as changing the on-screen style formatting and revising a book template.

I’ve also been learning more about what is involved with the overall tasks of maintaining single source with nearly 20,000 objects in your library. Objects can be topics or books or hyperlinks or index entries or graphics or… many other items, so I’ll have to dig deeper to get a sense of how many topic objects we deal with daily. Ah, here we go – do an Advanced unqualified search filtered for results Of type “Topic Object” and then select the ones not marked “Obsolete” or “Orphaned” (meaning not used in a book object) and the answer is, we have over 7,000 topic objects in our library.

I maintain that the learning curve is steep but I’m fortunate (or sometimes unfortunate) that I’m approaching these tasks with an idea of how I think it might work. Plus I have an Author IT expert sitting in the office next to me who still answers my IMs when I ask Author IT questions. (Thanks, Mary!)

Changing the state

It is still taking me a while to get accustomed to the workflow that requires that I change the state of an object before making edits to it. If the topic I want to edit isn’t in a writeable state, then I can’t make my edits until I locate the object so I can right-click it to change the state. Maybe I’m missing some shortcut to how to change the state while editing a topic’s text. I’ll have to poke around the tabs a while. It’s more likely that I need to make a shift in my workflow and remember to select the topic objects I want to edit, change the state, and then begin the edits.

Search mechanisms

My understanding is that there are two basic search mechanisms and both are rather underpowered for the amount of legacy information we have stored. (I’ll have to get a topic count to give real numbers here.) The first search mechanism is searching the entire collection of topics and books and sub books. The Advanced Search checkbox is always checked in my environment.

The second search mechanism is on the actual text within topics – you can search for text within a topic, within a book, or within the entire library. This mechanism is found from the Edit > Find menu command in AuthorIT Enterprise Edition.

What I’ve found recently, however, is that you cannot replace formatting on the found items. This limitation means that you could have semantically tagged items that are not able to be retagged. For example, if you had tagged all your menu items as “menucascade” but needed to change the tagging to “breadcrumbnav” you would have to export the topics to an XML editor and do search and replace there. I don’t yet know how to batch export say thousands of topics to do this search and replace to get the semantic tagging you wanted. This analysis and potential workaround is based on searching within the Author-it Yahoo Group’s messages, so perhaps there is another way to search for text and formatting and change both the text and the formatting but I haven’t found it yet.

Even with these two search mechanisms at our disposal, we find it easier to use a Google search tool on our external database at docs.imis.com, then right-click on the HTML page to get the topic ID, then use that topic ID to search the AIT object database.

Author IT Yahoo Group

Now, I just went through the Yahoo Group messages again to learn more about the searches in AIT, and I really do like the community there. People are very helpful and still maintain a nice sense of humor and goodwill. That’s an important aspect of any tool selection I think. Anyway, there is a way to search within a set of found items, and that is to do a Search using the Search tab first, then press Ctrl+A to select all topics found that match the search criteria, and then do the Find and Replace command on the selected topics. That search also revealed a potential limitation of AIT’s inability to find period space space and replace it with period space (explanation of why period space is correct, because The PC Is Not A Typewriter).

A third search mechanism that we could make use of but that doesn’t yet exist would be the ability to search within a folder. We can use the trick mentioned above where you select all the objects in a folder then do a Find. A Folder in AIT is just a representation of the objects in a collection within a folder in the CMS of AIT (sorry, too many acronyms to qualify as a real explanation, but it’s basically another view of the database but not searchable within each Folder). But that’s a find on text, not a find on objects or metadata on those objects.

Variables to substitute text values

I find that the variable mechanism is a little bit clumsy. Variables are simply text enclosed in angle brackets <substitutethisforthat>. So you still have to do a search and replace for text when you want to choose a different variable name. If you use angle brackets in your documentation, AIT has to be told specially that you meant to do that and that those should not be resolved to a variable name. So, if you really want angle brackets to appear as angle brackets and not resolve to a variable, you have to use the HTML trick of ampersand lt semicolon.

Running AIT publishing from the command line

One nice feature is the publishing engine’s batch processing that will even output the commands for you so that you can include it in a batch process. We found that the outputs are always placed within the users folder that is logged in to AIT, despite using a documented command line parameter where you feed in a user and password for running the batch processing. Mary found a nice workaround where she just copies the files she needs out of another folder (the _Output folder in our environment), but it seems like a waste of disk space to me to have a second copy of output in each user’s folder. We can do some cleanup using the batch files to ensure that disk space is freed up, however.

Magical price point

Let’s face it, since it’s in the four figures for a seat license, Author IT is a relatively inexpensive all-in-one single sourcing tool that has both a straightforward editor and a content management system. A small techpubs department looks pretty darn good when they can deliver manuals and help as part of an automated build in a lights-off no-touch system. And the savings in translation costs when you single source are unmatched.

Where AIT “feels” inexpensive though, is in the slightly outdated interface (why can’t it remember the window size after being shut down?), somewhat underpowered search methods, and so far, I just can’t shake the general feeling that you’re not really owning or editing “source” files but rather some Word-like representation of the source.

Still, it works wonders and lets our small techpubs department output some high-quality professional content, more content than possible without a single-sourcing tool. So I’ll face the learning curve and continue to climb it.

Subscribe to the comments for this post

Initial review of AuthorIT

I’m now writing in an AuthorIT environment. My first learning task is to find out the proper pronunciation, is it Author Eye Tee? Or Author It? Let’s see what wikipedia has to say about AuthorIT. In their article, they consistently refer to the product as Author-it, so I would suppose the second pronunciation I proposed is the correct one. Plus, the AuthorIT website has Authorit throughout. Internally we call it AIT for short.

At first glance, the product looks and feels like a database-centric content management system because of the initial connect you make is to a SQL Server database. But in fact the way you browse the system is folder-based, as if I were using Windows Explorer. So far, so good, except that I’m not yet completely familiar with the way that the CMS folder structure is set up based on our Function-based teams. However, we have a Helpsite that lets me browse the current content in another way and has a decent search mechanism and index to allow me to look for the topics I’d need to update.

What I’m doing now to get started as a greenhorn with both the toolset and the product I’m documenting is to peruse the Helpsite which is organized by tasks and features of the product, and then determining what topics need updating for the particular feature I’m working on, and then right-clicking and getting Properties on the page I want to update. Next, armed with the five-digit number that the HTML file is named, I do a search in the AuthorIT database to find that exact topic, and then make my edits. Whew.

One incorrect assumption I had going in to the AuthorIT environment was that editing is all based in Microsoft Word. Not true at all, my AIT trainer protests, the editor is AIT’s own, but AIT does a good job of outputting to Word formats and you can use VB macros to format the output as you wish. I’m still learning so I’ll let you know what other incorrect assumptions I’m finding otherwise about.

The other thing that strikes me right away is that while it’s topic-based and structured authoring, all the things you create are either books or sub-books. I wonder if that interface could be changed to refer to deliverables or some other such generic term that isn’t loaded with a print connotation. It’s a minor nit to pick, that the loaded term “book” is so prevalent, but many other editors and CMSes have gone beyond the book terminology so I was surprised it still lives in AuthorIT.

To be perfectly honest, I wasn’t all that impressed with the available outputs. Here’s the list from the AuthorIT website: (hey, I would have given you all a more precise link, but when I clicked Publishable Outputs in the sidebar in that page, I got a page not found error using IE 7 on WinXP SP2.)

Publishable Outputs

Print

• Printed Documentation (Word, RTF, or PDF)

Help

• WinHelp
• Microsoft HTML Help
• Sun JavaHelp
• Oracle Help for Java
• Vista Help (Upon Release)

Web

• Web and browser based Help
• HTML 4.01 + CSS (W3C Validated)
• XHTML 1.0 + CSS (W3C Validated)

Presentation

• HTML based slide show Presentations

XML

• XML
• DITA

The first omission that comes to mind is the lack of Eclipse help output. There’s also no Flash help output. In addition, I wanted to analyze further on the usability and look and feel of the Web and browser based help, especially with the recent article complaining about DITA’s lack of a cross-browser “Web help” like what Robohelp outputs as well as the lack of FlashHelp output. There are a couple of good articles out lately about it. There’s an article on ditausers.org comparing Help Authoring Toolkits to the DITA Open Toolkit. His output comparison matrix for DITA points out the lack of a webhelp equivalent for DITA Open Toolkit transforms. Here’s Tony Self’s recent analysis on Writer’s UA website. But I’m not talking about DITA necessarily, unless I was going to propose outputting AuthorIT to DITA and using DITA transforms for publishing, a workflow that I’m not proposing because it just seems too roundabout and more difficult to automate.

Anyway, my first glance at the AuthorIT web help output is that it’s a little bit antiquated but it is tripane and it does have contents and index tabs but no search tab according to the demo on the AuthorIT site. Frankly, without a search function, no help system is complete. With a quick Google search, though, I learned from Char James-Tanny that “by default, AuthorIT does not include a search tab, although the Help file does include instructions for hooking up a free CGI search.” That article appears to be dated January 2003 so I would have to do more hands-on testing to determine the quality of the search and the ease to implement it. Interestingly, in that article she mentions using AuthorIT as the CMS and editing environment and then using RoboHelp for the more feature-rich output engine. I wonder if that’s still a viable toolkit and publishing engine combination now that Adobe is developing RoboHelp.

Writing an article like this one while I’m still very inexperienced with AuthorIT is risky because I will read it later and think, “why would I proclaim my ignorance in a public manner?” But I believe it’s important to capture initial thoughts and reactions while they’re fresh in my mind. So bear with me while I analzye the authoring system and the publishing system and draw some perhaps premature or immature conclusions.

Subscribe to the comments for this post