Using Author-it

Posted 8 October 2010 by


When you write something, how far do you break your text into? How do you handle repeated text or boilerplate text, particularly between different things? Can you reuse portions of your text in other contexts? If your writing needs to end up in different formats (printed, web, PDF), how do you generate the different formats?

I recently was working on an editing project using Author-it for Microsoft Dynamics CRM. In many ways, this tool turns your normal writing process upside-down, and inside-out. Yet, this tool allows you to write once, but use portions of your writing in many different output formats and different documents within the same format.

In Author-it, everything is based upon an object. Objects may be limited to one or more versions of output. Different objects may be gathered in “book objects” to create a single document (or web page). An object may contain one or more objects, or only another object. How granular or global do you want to get?

This has uses in technical communications. If you are writing about a search function, creating a specific object to describe or name the button you click to perform the search is a wise thing to do. Today that button could be the Submit button. Tomorrow it could be the Search button. Changing the object with that button’s name is the only thing necessary to change the name of that button throughout your documentation. Not only that, the change can be restricted to specific versions of the software.

How this turns things around is how you start to think about the document being created. (Document can mean web page, book, Microsoft Word document, XML, or most anything.) You start thinking about the granular aspects. If describing a process for an article, have the specific steps been recorded somewhere else, like a Help topic? If so, create an object for the steps for use in the Help topic and your article.

With the article broken into enough component chunks, you assemble your finished product. Then, if a component chunk updates, it content updates everywhere it is used. Remember that you can specify which version of an object to use for a specific output.

This solves the problem of how to change the content everywhere if one thing changes.

It also creates the problem of unintended consquence of how something reads in one place if changed for another place.

As you can probably guess, when creating output for localization for a large web product, the processing time for the server can be more than trivial. The project I was working on had the sequentially numbered objects numbered over 50,000. Some of them were for Microsoft Dynamics CRM Version 4. Some were for only the web version of Version 4. Some were for only the on-premesis version of Version 4. Some were only for using Version 4 with the plug-in for Microsoft Outlook. Repeat all of this for Version 5. And, some of those objects are for Versions 4 and 5.

Fortunately, the output is being localized (into over 40 languages) in different handoffs. But that means that Author-it had to be able to distinguish between groups of files for the same version, but different handoffs.

When creating output for the last handoff, I was moved over to editing the software development kit (SDK) for a short period of time. Creation of the the Microsoft Dynamics CRM SDK is in DxStudio, a tool that produces XML using Microsoft Word at its core. This meant I was not trying to use Author-it at the same time.

I found Author-it to be somewhat intuitive, not perfectly intuitive. And, the right-click to open a menu of commands was my friend. Many other people find it, shall we say, to be much less intuitive than I do. Then again, being a long-distance friend of Char James-Tanney probably transferred knowledge to me by osmosis. Well, at least transferred knowledge to me by listening to Char describe how great a tool Author-it is.

There were some issues. One was that the implementation of Author-it used by the Dynamics CRM team was unable to translate a multiplication sign (×) in an object to proper HTML. This is a problem when describing screen resolutions. Using an “x” (600 x 800) in place of a multiplication sign (600 × 800) causes a problem for those using adaptive technology to “read” the content to a person. You really want the screen reader to say “Screen resolution needs to be at least 600 times 800,” and not “Screen resolution needs to be at least 600 ex 800.”

(Adaptive or assistive technology helps everyone, not only those limited in some area of life. This is one of the things I learned while working as a safety inspector right after graduating from college. Limiting a weight lifted to 40 pounds cut down on worker compensation claims for everyone, not only those of smaller frame size. Using the correct symbol in HTML means anyone can scan the text quicker and get the right meaning the first time.)

There were a few other internal translation problems, such as creating the correct level of bulleted text—if bullet point was even used. Solutions for these problems were still being created when I left. These would not necessarily affect localization, since it would not affect what was said. These things only affected formatting.

Since these objects started from an import from DxStudio, we may have had problems other implementations of Author-it do not share.

I am not in a position to compare Author-it to Adobe Framemaker. From what I know about Framemaker, I would not want to try to this tool in the same way Author-it is being used by Microsoft Dynamics CRM.

I have had an oportunity to use conditional text in Adobe RoboHelp. There are many things RoboHelp does very well. I have made it run and jump through a hoop more than once. Still, my feeling is that Author-it and RoboHelp are in different leagues. The level of output customization in Author-it is much more granular and easy to update in limited situations.

If you are looking for something to keep some HTML on a website updated, Author-it may be overkill. Many content management systems can handle keeping text blocks up to date. But, being able publish different versions from the same database is something that will not happen easily.

If you have to deal with versioning issues, give Author-it a look.

Related posts:

Post Details

Leave a Reply

Page optimized by WP Minify WordPress Plugin

Writing on a VTX is Stephen Fry proof thanks to caching by WP Super Cache

Better Tag Cloud