Author-it migration to version 5

Here’s a report from the acceptance testing we’ve done to go from Author-it 4.5 to 5.x.

I don’t know if anyone else had difficulty understanding the best migration strategy, but I thought I’d talk about my misunderstanding in case it helps others. At one point, we thought it might be a good idea to take only new content to 5.x, giving us a chance to test for a long time before relying on 5.x for our production. I also wasn’t sure how we were going to go from 4.5 on SQL Server 2000 to 5.x on SQL Server 2005. To get a two-server environment (4.5 and 5.x, 2000 and 2005) I thought exporting to XML would be the way to go – as long as we got all dependent objects, we should be able to start fresh by basically populating the default database. There were so many additional steps to try to export content that it turned out a wholesale upgrade of the database was a much easier route.  We just had to put in an IT request to create a .bak file of the SQL Server 2000 file, then have them restore that .bak to SQL Server 2005. All our users, variables, everything came over that way and all we had to do was “open” (connect to) the SQL Server 2005 library with Administrator and the upgrade went quite quickly.

I also offer our notes from acceptance testing we did last fall. I haven’t yet logged any oddities we’ve seen but will try to do so in the coming weeks. So here goes!

Author-it 5.1 Acceptance Testing

As a preliminary test, three authors tested a SQL-Server based Author-it test database for an hour simultaneously on 8/15/08. This report contains our notes from the testing session and further discussion as we researched some of the difficulties we found.

Overall

Performance

Anne said it seems sluggish to open a topic, but Melissa found it normal.

Anne: Creating a new topic using a template is slower than 4.5.

Usability

Anne:

  • Why does it use Times New Roman for all the topic titles in the Book map view? Guess it’s because of my Windows theme which uses a serif font for titles.
  • Change in how to set up options: click the big A, then click Author-it Options. You’ll want to be sure to select the Auto save all open objects every n minutes on the General tab since we’re accustomed to the Auto save feature, since it was automatically enabled in 4.5.
  • If you double-click the Big A, you close AIT.
  • You can’t see anything on the Change Release State menu when in the Book Editor.

Daily work

This testing involves the writing and authoring aspects of Author-it.

Editing

Melissa saw no problems.

Anne:

Regular typing and over typing seems like business as usual. See links notes and style notes as well, though.

Authoring

Anne:

Creating a new topic has more clicks because of a new folder – the AuthorIT Website Manager folder. Can we get rid of that nesting somehow?

Melissa:

No problems creating a new topic, basing it on a template, and adding content.

Strange saving behavior in the book editor:

Procedure: Edit a topic in the book but don’t save your work. Move to another topic in the book. My work was saved.

Procedure: Edit a topic in the book but don’t save your work. Close the book object before moving on to another topic. My work was NOT saved. It did not give me a warning that I had unsaved work. AIT4 used to issue a warning in this situation.

Procedure: Create a new topic in a book, add content to the topic, save the topic, and close the book. When I opened the book after closing it, the topic was not in the book. However, the topic is saved in the folder that was selected when I created it. I realized afterwards that I did not click the icon to save the book as well. It did not warn me that I had unsaved work.

Lesson: Always be sure to manually save your work to the topic AND the book. You will not be warned if you are about to lose unsaved work. Melissa did find the setting changed from 4.5 to 5.1 in the Author-it Options dialog box. You’ll want to be sure to select the Auto save all open objects every n minutes on the General tab since we’re accustomed to the Auto save feature, since it was automatically enabled in 4.5.

Applying styles

Anne:

Applying no paragraph styling is a little easier, but the nested style menus with folders makes for more clicking.

Melissa:

I don’t like the paragraph and character style selection lists. After clicking the dropdown arrow and then Styles, I can’t do two things that I could in AIT4: I can’t use the up and down arrows to scroll the list. I have to click the up and down arrows on the screen. I also can’t type in a letter to jump to the style I want in the list.

I can no longer right-click a selection to change the style.

Searching for words within a book object

Anne:

Very fast for search, but replace was dogged for just 9 instances in the 2_Casual_Contact_management sub-book. And the progress bar showed 7 of 9 but then the final dialog box showed “23 replacements made.” That’s a little unnerving.

As far as I can tell, you still can’t search for certain words with styles applied and then replace with another word with no style applied.

Melissa:

Works better than it did in AIT4. In AIT4, if I used this search function more than a couple times, it would stop highlighting the words consistently. It is working consistently so far in 5.

Searching for a topic or other object within the library

Anne:

You just choose a different dropdown menu to change the scope of find and replace, which is nice. But when you choose “Look in: Library” there is no Replace All choice? And no way to “Find Next” when what was found isn’t what you were wanting to replace? Example: Search for Contacts and replace with <tContacts> in the whole Library.

Melissa:

I love that we can now search for objects within a folder. This limitation was frustrating in AIT4.

When I switch between the Folders view and the Search view, the main pane changes accordingly, as it should. In AIT4, after I searched for an object and then clicked Folders to return to that view, the search results would remain in the main pane. I would have to select a folder for the main pane to refresh. This is a good change.

Showing relationships

Anne:

Looks great to me. I like the new tab that shows “Books using this topic” in the Book Editor.

Melissa:

Works like it did in AIT4. No problems that I can see.

Importing graphics

Anne: Double-clicked a graphic in a topic in the Book Editor to change it, and AIT opened a Properties dialog for the graphic, but I’m not sure how to replace the graphic with a new one – ah ha, the menu changed. You don’t click the little triangle/circle/square icon, you click Insert or Open menus.

Melissa: No problems.

Creating sub-books (Create a technical review excerpt)

Couldn’t create a DT excerpt because the template did not get imported due to no dependencies on that DT excerpt template object, but just made a User Guide book.

Inserting variables

When creating the <pi> variable, I couldn’t choose Char – iMIS as a style. It must not have been brought over? Added that note to the list of items we’ll have to add to the database after import.

Apply release states

Anne:

None of the imported topics kept their release status.

You can only apply release states in the folder explorer view, not by right-clicking in within a book object.

Melissa:

Topic release states can not be changed in book editor view. You have to select the topic from its folder location, and then the available release states appear.

Apply template

No problems. Creating a new topic using a template seems slower than 4.5.

Create links

When I drag a topic and choose Hyperlink: Jump, it adds (|Hyperlink: Jump) to the text on the hyperlink.

Advanced work

This type of work involves publishing and other not-so-daily tasks.

Versioning (Branching topics)

Bulk object duplication-select a range and clone a whole set.

Publishing

Publishing looks to be slower, perhaps 30-50%, but we would need more content in there to fairly compare.

Anne: our later tests on 5.2 found probably speeding up of publishing from 4.5 to 5.2.

Automated building

Promising aspects of 5.x: publishing profiles, variable variants, which offer conditional content control: allows maintaining multiple release versions in one library.

List of what must be added to the database after importing content

  • Users and their roles
  • Variables
  • Any style that is not used by content, such as Char – iMIS
  • Release states
  • Folder permissions
  • DT Excerpt books and other special books not brought over after importing

What we’ve found since doing a content import is that it’ll work well for us to migrate content to a database rather than imorting content.

4 Comments

  • April 14, 2009 - 8:30 am | Permalink

    You can (in the 5.25 update) set release states from within a book, and I think a couple of the other issues you mention have also been addressed already.

    And FYI, we upgrade from 5.1 to 5.2 without a hitch.

  • Asha
    May 7, 2009 - 12:30 am | Permalink

    Hi Anne,

    Very useful article! Thanks for sharing it.

    Regards,
    Asha

  • September 10, 2009 - 8:08 pm | Permalink

    Does anyone know of a community to support the IT ADMINISTRATORS who have to support Author-it? Their documentation seems quite good for the users, but for those of us installing, maintaining and troubleshooting, it’s pretty sparse. Thanks

  • September 11, 2009 - 7:57 am | Permalink

    I don’t know of one off the top of my head but it seems like you could start a group for IT people supporting Author-it. It’s a great idea. Documentum has more specific communities, maybe Author-it could do the same. I can send it in as a suggestion. Thanks for commenting!

  • Leave a Reply