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.

Subscribe to the comments for this post

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

Corporate blogs learning from reviewers

Diane Wieland has a great post at the Duo Consulting blog called Free Expert Blogging Advice that points to the Fortune 500 Business Blogging Wiki. In the blog entry she encourages bloggers to learn from the reviews of blogs using a standard set of criteria found at Business and Blogging. They say:

Good Blogs will be:

• easy to find
• frequently updated
• written in an engaging manner
• relevant
• focused
• honest
• interactive
• responsive

Bad blogs will be:

• hard to find
• infrequently updated
• censored
• one-way communication
• unresponsive
• defensive

Ugly blogs will be:

• boring
• inaccurate or misleading
• filled with technical jargon (for a non-technical audience)
• full of regulations and legal disclaimers
• self-absorbed
• press releases in disguise

It would be interesting to apply these review criteria on technical writing tool vendor’s blogs. MadCap has what I consider to be a groundswell-blogger-style with personalities first, company second. Adobe’s Technical Communication Suite team’s blog has a distinct corporate and enterprise appeal while still identifying posters by name and letting you get to know them. ComponentOne has a collection of blogs and bloggers but buzz generation fills the first page. Author-it has a new nicely branded Wordpress blog. WebWorks has a group of bloggers also and Alan Porter is my favorite blogger there. TechSmith hosts three blogs – the Jing Blog, Screencast.com Blog and The Visual Lounge Blog.

I won’t apply bad or ugly criteria to any of these. I’m happy they’re blogging. What are your thoughts as more and more of “our” vendors begin to join the blog world? Have I missed any of your vendor favorites?

For even more corporate blogging resources, see the link list on Rhonda Bracey’s post entitled Corporate/business blogging.

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

Can DITA train writers? Or does it require too much programming?

DITA for writers (content creators)

I just did a search on amazon.com for books for beginning technical writers and also to investigate what books are being written for our profession and for others wanting to start in our profession. I came across a book called Writing Software Documentation: A Task-Oriented Approach that suggests three categories for writing:

• writing to teach (for eager learners)
• writing to guide (for reluctant users of the product)
• writing to provide a reference (for experts who need only occasional support)

I immediately saw a connection to the three content types that DITA prescribes:

• concepts to teach understanding
• tasks to guide performance
• reference to offer facts or lists of information

Because writers have to immediately place the information they want to record into one of these three types of information, they are being trained on how to write in a task-oriented, performance-based manner, via DITA. I am especially interested in this “training” for wiki authors and talked about the idea at our recent presentation at the Central Texas DITA User Group meeting.

DITA for publishers (formatters)

Recently a few techpubs bloggers have been talking about DITA and its weaknesses, such as a lack of online help outputs, and how difficult it can be technically if you don’t already have a staff with pseudo-programming skills. Gordon Mclean writes “DITA is not the answer” and I think the question he is trying to answer is, “what is a single-sourcing tool we can use in our environment (which includes Technical Communications, Training, Pre-Sales and Marketing) with our current resources?” Instead of DITA, it looks like he’ll go with Author-it.

Since I just this past year moved from BMC, which is still moving to DITA, to a small techpubs group that uses Author-it, I can understand his reasoning and agree with his business case assessment. The toolchain for DITA is very nearly there, but often a CMS-based approach has too much overhead for small companies. It can be cost overkill when you have few topics to contain.

Scott Nesbitt followed up with his post, “DITA’s not THE answer for single sourcing.” I think he’s spot on with the analysis “it’s difficult to get good PDF or online help from DITA without extensively customizing XSL stylesheets or passing DITA source files through tools like FrameMaker, Flare, or WebWorks.” One of his commenters said something about consultants smelling blood in the water, yikes. In other words, I think he meant that XML consultants knew how much customization would be desired and can have a feeding frenzy on the potential work possibilities. My guess is that the people who have been around XML for years know that there are still basic needs for output, and their experiences have shown them that nothing that is structured is an “out of the box” experience. So much of the success depends on your content to begin with.

I’ve found the same conclusions about the output in my experience. When you dig into single sourcing, be it with DITA or another tool (Madcap Flare, Author-it, FrameMaker, RoboHelp, and the Adobe Technical Communication Suite) the real business-case killer seems to still be, where can I get pretty PDFs that are formatted just as I like them? With DITA, one answer is to go get the Mekon FrameMaker plug-in for the DITA Open Toolkit. No XSLT-FO knowledge required.

People love their tools to get their pretty PDFs or sleek online help systems. Plus, so many of the employers out there have a lot of content that looks pretty nice already in a specific tool. The legacy documentation may be one reason why hasn’t DITA helped our industry get away from tool love. Tech writers and their employers fall in love with tools. I’m not saying Gordon or Scott are tool lovers, but certainly some people they’re hiring will be. There is probably also an element of “if it ain’t broke, don’t fix it.”

DITA for all?

Sarah O’Keefe has a thought-provoking analogy in her comments on her post signed “DITA Dissident.” The analogy is that creating desserts using a frozen pie crust is one method of getting results. If a pretty PDF is your ultimate dessert, then for some, DITA is a bag of flour, meaning you’d better be a skilled baker if you’re going to use it for the best pie (PDF) ever. For others, DITA is a frozen pie crust that makes a perfectly good cherry pie (PDF) or apple pie (plain HTML) or chocolate creme pie (Eclipse help). Although isn’t the filling the content and the pie crust the DITA map?

Their conversation first started with Eliot Kimber discussing DITA’s use for narrative documents. Alan Porter talks about DITA use for narrative writing as well, but in a different line of thought in his post, Is DITA Just a Story?

All the posts I’ve linked to are enjoyable for me to read and to point to and to think about. I’ve read it before, and I’ll say it again, I believe along with others that DITA has the potential to transform our industry. Just last night I said to the San Antonio STC group, today we all speak HTML tags pretty fluently. In ten years, will we all speak DITA tags just as fluently? “I wrote the shortdesc according to the guidelines and it works for the topic, but I am not sure if my conref target is going to be there every time. I guess I should rewrite the concept topic.” Heed the warnings and experiences of others before making the leap to topic-oriented single-sourcing or your expectations and those of your customers may not be met.

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

Q and A about Author-it and DITA – guest post from Mike Stockman

I read this recent conversation on the author-it-users Yahoo Group with interest. I haven’t had a need to author DITA topics with Author-it, so I have to rely on others for information on how it works. With Mike Stockman’s and Tony Watkin’s permission, I’ve written their Q&A as a blog entry.

Tony: What are your experiences with using Author-it for DITA output?

Mike: The DITA output is partial. That is, they don’t support a lot of DITA features, so that most table definitions are not passed through, bookmaps aren’t supported (although ditamaps are), reflinks aren’t supported, syntax diagrams aren’t supported, and so on. However, it’s definitely usable, so that AIT puts out the four DITA topic types (task, reference, concept, and base) properly structured, index entries are supported, tables and images are handles correctly, and so on. The best test would be to publish to DITA and see whether the results are what you’re expecting.

Tony: Is there a mechanism provided by AuthorIT for being able to search within the DITA XML generated output afterwards from within the browser when accessing the DITA output directly from the browser (i.e. not via AuthorIT)?

Mike: There is no mechanism provided by AIT for viewing DITA output. Once you have the DITA output, you can either view the XML code, or transform it into something more viewable, such as XHTML or PDF. Grab the DITA Open Toolkit, available at <http://dita-ot.sourceforge.net> for all of the tools you’ll need to transform the DITA into something else.

Tony: Also, does AuthorIT just output XML when publishing DITA or does it also produce corresponding XHTML?

Mike: AuthorIT publishes DITA by first publishing to XHTML, and then transforming that to DITA. It does not, however, leave the corresponding XHTML behind, so you can’t view it. Your choices for viewing XHTML would be to either publish from AuthorIT to XHTML directly, or transform the DITA to XHTML.

Mike’s final comments

AuthorIT’s DITA is not a fully-developed DITA solution, so don’t expect it to be. Instead, AuthorIT’s DITA output is great when you have a need for single-sourced output to multiple formats, such as if you needed Word, XHTML, *and* DITA. Where I work, for example, we use AuthorIT’s Word output for our printed docs and PDF, and use the DITA output to create our online help. If you need the advanced features of DITA that AuthorIT doesn’t support, I’d suggest going to an all-DITA authoring environment and avoid AuthorIT altogether.

Subscribe to the comments for this post