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.

11 Comments

  • September 27, 2007 - 5:47 am | Permalink

    Hi, Anne :-)

    I just wanted to answer or address some of your comments :-)

    - Angle brackets around words only resolve to a variable if such a variable exists. For example, if you want to use in a topic, and you don’t have a variable called “html”, then it will display as typed. However, if you want to use in a topic and you *do* have a variable called “html”, the easiest solution is to embed a non-printing space somewhere in the variable name. That space will prevent the variable from being resolved, and then won’t display when published.

    - Right now, only the floating license is in the four figures. I believe a fixed Enterprise license is under $1000, in the same price range as other HATs.

    - The interface has gotten a complete update in v5, which was announced this week.

    - I have to check replacing “period space space” with “period space”. AIT won’t let us do something like replacing one character with nothing, but the example you quoted should work fine.

    Unfortunately, the search has some issues. I usually publish to Word and search the results when I’m doing that kind of stuff.

  • September 27, 2007 - 9:33 pm | Permalink

    Hi Char – Thanks for the explanations. I had to laugh when I saw the v 5 announcement literally the day after I posted this entry. The last possible day I could complain about the outdated interface, they announce they’ve updated it! Too funny. This post is a great example of why it’s important to give early copies to bloggers, ha ha. :) But I honestly don’t mean any negativity. I am excited by the screenshots alone and have already cleared my calendar for next week’s webinar peek.

    I do find it interesting that you publish to Word to do more extensive searches – so, do you make the search and replace changes in Word and then re-import into Author-it? I guess that’s the only way we could replace instances of a variable that has been italicized inconsistently. That’s a lot of work though since we have over 7,000 topics in our library.

    Oh, and how can someone get the three-figures pricing for a fixed Enterprise license? I walked through their quote system on the website and got something like $3,209.43 for three Author-it V4 Enterprise Edition Fixed Licenses. So I guessed it was in the low four-figure price range. Ah, the mysterious art of software pricing. :) Although low four figures isn’t much different from high three figures.

    Thanks for the info!

  • September 30, 2007 - 8:44 pm | Permalink

    Hi, Anne :-)

    I did a session at WritersUA this year about HATs and was given permission to announce the updated interface then. ;-)

    I do not do the searches and replaces in Word and then re-import…I do spell-check in Word and then find the right topic in AIT and make the change. Same with anything else. BTW, one way to take care of character formatting on variables is to assign the formatting directly to the variable in the Administrator…much easier than having to remember to apply it when creating topics!

    However, another method is to export the book to XML, make the changes in an XML editor, and then re-import the XML back into the library. Unless specified differently, the existing topics will overwrite their counterparts…new topics will not be created.

    And the pricing model has changed. I don’t know what the new prices are yet.

  • Shannon Greywalker
    October 1, 2007 - 9:50 am | Permalink

    Anne – AIT can indeed remember your last window size/position. Tools > Options > View. Select both the Save window positions and Save window size checkboxes and you’re golden.

  • Shannon Greywalker
    October 1, 2007 - 10:00 am | Permalink

    The main reason I prefer searching first on our published Helpsite is because the search results are then viewable in a full output context that shows me position in the overall TOC. Also, the hyperlinked nature of the published Helpsite makes it fast and easy to check several potential hits to find the right one.

    When you search within AIT itself, you have to use Locate or Show Relationships to determine the context for a specific topic.

    So which search approach I use depends on what I’m trying to do. If I’m researching a bug report and trying to figure out who the nominal owner of a topic might be, it’s more useful to do a Helpsite search to see what books the topic is used in. On the other hand, if I’m trying to search/replace all instances of a string (such as when we change the name of something and I suspect that the name is hard-coded instead of abstracted in a string variable), it’s quite convenient instead to search within AIT and then open up the result set one topic at a time to work through the revisions. In this case, I don’t care about the context for each topic.

  • Shannon Greywalker
    October 1, 2007 - 10:10 am | Permalink

    Regarding state-changing and workflow, it’s helpful to remember that the release states for AIT objects are intended to be used as flexible metadata rather than as workflow flags per se. If you don’t think of them as tied to workflow, they won’t get you in trouble. In our shop, they’re more of a static indicator of “readiness for publishing”.

    There are essentially three reasons that you must manually change the release state of *some* objects before you can modify them:

    * To provide an at-a-glance overview of which topics are completely unchanged/untouched from the last release (our “baselined state”)

    * To force an author to set an informative state when they decide to make changes to a baselined object (otherwise it could be possible to forget to change the state from “baselined” to something else).

    * In the case of “Branched” topics, to remind an author that they must make changes not only to that one topic, but also possibly to all other branched versions of that same topic (same object ID but multiple versions for future release branches).

    All other topic types (that aren’t obsolete/deferred) are editable without first needing to change the release state.

  • October 4, 2007 - 8:21 am | Permalink

    Shannon – thanks so much for the tip on Tools > Options > View to get AIT to remember the window sizes, excellent! And I appreciate the lessons on state changes and search. The state change is the concept I’m slowest with I think. :)

    For the record, we attended the webinar yesterday and I’m jazzed about the new interface. And the Publishing Profiles are going to be great to implement.

    Char – thanks again for the helpful info. We do indeed assign the formatting directly to the variable in the Administrator… and our output is fine, it’s just that I’m being nit picky about the fact that the source is tagged incorrectly if someone italicizes a variable that is already formatted as italic in the variable itself.

    Your export to XML and re-import is the right thing to do here, if we do want to ensure that the source variables are correctly tagged. It’s good to know the topics won’t be duplicated, thanks for that expert info!

  • Ann Ortha
    January 15, 2008 - 11:22 am | Permalink

    Beware, the 5.0 update has major problems and the latest advice from Author-it support is “don’t use it in a production environment”.

    They already acknowledge that imports are broken (crashes on word imports, takes hours, literally, to import a small XML file), publishing is very slow and broken (word docs come out with randomly missing headings and paragraph breaks), editing is broken and tables within topics will be corrupted whether you import them from a prior version, or paste them in from word, or retype them line by line.

    Search /replace doesn’t seem to work properly, editing (particularly in tables) doesn’t stick, and there are whole chunks of missing functionality throughout the UI.

    Overall the program is really slow and clumsy. It crashes easily, and it generates huge log files. The licensing model is incomprehensibly strange and intrusive — is piracy really that big a problem that they need to put this much overhead into the code to remind us to behave ourselves?

    Apparently they are working hard to fix these issues, but if they themselves aren’t confident enough to recommend using it, then it really is not a release version.

    They must know that their customers are typically very well versed in software development cycles, QA testing, release criteria and so forth, so it’s just amazing that such fundamental problems in this application could be present in a so-called release version.

  • January 12, 2010 - 5:05 pm | Permalink

    I have been trying to import html files for our website but it keeps hanging up around 49% and then I need to go to task manager to cancel it. Any ideas on what would hang it up?

  • January 12, 2010 - 5:19 pm | Permalink

    Could be any reason from Javascript to unclosed HTML tags. When I have to do troubleshooting, I’ll search the old http://tech.groups.yahoo.com/group/authorit-users group or go to the new one at http://my.author-it.com. Rhonda Bracey recommended cleaning up the HTML before import with a tool like FAR, http://helpware.net/FAR/.

  • May 29, 2012 - 1:27 pm | Permalink

    For search and replace of styles in Author-IT, we just released a plug-in. It’s not free, but it costs less than an hour of your time.
    http://www.tech-tav.com/products/authorit/plugins

  • Leave a Reply