just write click

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.

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.

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.

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.

Happy thanksgiving everyone! I have much to be grateful for. Here’s me with my son, both of us stuffed full of turkey.

Deadline extended… multiple meaning

I just learned that the Give 1 Get 1 program to purchase two XO laptops has been extended through December 31st. Hurrah!

I’ll admit it - my first thought was, good, I can delay that $400 escaping my bank account until after the holidays. But my second thought was, “Say, we can work more on the simplified user guide to get a nice PDF and even more language translations!”

Wiki writing workflow

I said I’d try to describe the workflow of wiki to Author-it. It’s pretty feeble and I really want better ideas so feel free to offer up your thoughts here.

Some history on the legacy. The file started out as a Google Document, which basically meant it had nice clean HTML code underneath and could be written on collaboratively and shared discerningly. The links to the wiki URLs were actual URLs rather than the wikitext linking code. The text contained a bit of passive voice and was more descriptive than task oriented.

Always start with task analysis

Once I read it, I did some task analysis, which is available in this published Google spreadsheet. I broke down the tasks based on whether the user was a kid, a parent, or a teacher using the XO. Then Emily Kaplan and I started re-writing the sections and adding section (or topics) based on the task analysis. First we tried writing each topic as an unpublished WordPress blog entry, thinking that we could eventually get translations done using the Worldwide Lexicon open source initiative. An interesting concept, perhaps well-matched to the spirit of the OLPC project, but we learned that maintaining a Table of Contents would be difficult, and also found that the Laptop.org folks like SJ Klein really wanted the wiki at wiki.laptop.org to be the source for all content.

Wiki as source

I completely agree with this wiki-centric approach and we have adapted. All the WordPress entries (there were less than eight of them) went into the Google doc, and then Todd Kelsey “wikified” the Google doc by saving it as Word, then using a visual basic script to convert to wikitext. We lost all the graphics placement but were able to get a wiki page going with the Google doc.

Word to Author-it…

During the same week’s time, I had taken the Word document saved from the Google document and imported it into Author-it in the instance donated by Author-it (thanks so much) on a server donated by Hostway (again, thanks) and that import worked really well with graphics and links and pretty much everything intact.

Wiki to Author-it… and back again

But this is where the wiki as source becomes difficult, right? Any changes that are made to the wiki must come over to Author-it, and that’s a manual and “think-tual” process. And I’m behind and should stop writing this blog post and go work on synching and writing more topics based on the task analysis.

Localization

As far as translations go, there were several translations done of the document when it was still in Google docs. Interestingly, many of the translators wanted Word documents to work in. Again, though, with wiki as source, I have linked to the translated files in hopes that others will pick up and wiki-fy the translations. One area I’m still learning about is whether the wiki engine has tools for the editors of translated pages to keep up with changes made to the English version and vice versa (if changes were made to the Spanish version of the wiki page, how could we incorporate those into the English version of the wiki page?)

Wikitext, wikitalk

I’m learning so much more about wikis (especially wikimedia) from this hands-on experience - such as “signing” notes with ~~~~ to get your username and a time date stamp automatically, and using “talk” pages to communicate with others on the wiki by posting notes for another user.

XO User Club in Austin

I’m also committed to starting an Austin-based XO User Club, following Robert Nagel’s lead with his excellent blog post and article in OLPC News. Let me know your thoughts here - I would like to see if we could meet at one of the Austin public libraries, probably on one Saturday a month (although we’ll be competing with soccer and other Saturday activities). We might have to play it fast and loose for a while and see what type of core group we gather. There’s a User Groups wiki page at http://wiki.laptop.org/go/XO_Giving/Users and it’s great to see where the groups are cropping up.

How to help

If you’re interested in writing more of the user guide for the laptop, all are welcome to contribute to the wiki page at http://wiki.laptop.org/go/Simplified_user_guide. Use the task analysis as your starting point if you want to start a new topic. I’m also seeking a page layout person with Word expertise to get a nice square manual that Lulu.com could easily print. Graphics to explain procedures, especially using the Activities, are always welcome over text. Join the OLPC Library mailing list where we discuss documentation and e-books for the XO.

Also, consider using the give one get one program to give the “get one” to some deserving kid in Austin, especially now that the GIG1 offer is extended. I’d buy ten of them if I could, to start the XO kids club with no “entry fee.”

Also, join us at the XO club meetings, with or without an XO, if you’d like to bring your Linux or Windows laptop and emulate Sugar, the XO’s operating system. EToys and TamTam experts are welcome.

Everyone, please give the TechWriterVoices.com site a look or two or three or more. It’s such a great site. I’m not just saying that because I have a podcast there now, Answering Tough Questions about Wikis - Anne Gentle, but because I do want to tell everyone what a great interviewer Tom Johnson is.

Tom sent ten excellent questions ahead of time via email and I spent some time answering them by writing out some notes. I’ve sharpened them up for those of you who, like me, don’t really have the auditory learning style that listening to podcasts serves best. I always want to be able to scan my media and pluck out the pertinent tidbits, and few podcasts have that feature. (Side note: with QuickTime movies you can make chapters which allows you to scan the chapter titles for the content you’re most interested in.)

So, here’s the interview in text form, but not a complete transcript. We skipped around, Tom edited around the audio difficulties, and sometimes I just answered the question differently.

1. How we can manage and re-use content when it’s wrapped up in mediums like wikis? Can you single source topics? Can you export the content to Word? Or is it locked in its own format?
Nice lead in. This is the ultimate question that many people are asking me and I am having lots of conversations via email and lunches, trying to come up with ideas.

Wiki engines are becoming more and more powerful and CMS-like. WikiMatrix.org has 95 wiki engines listed as of this week. Yes there are still very simple wikis but there are also people making wikis run really powerful websites with amazing wiki extras - like threaded comments, conflict resolution, and so on.

But about single sourcing and wikis…

One idea is that you export your source to a wiki, and then when any changes come in, have to have a human cull through all the edits and figure out what should go into your souce files the next version of the wiki should be, like book publishing. This method is similar to going through support forums or support call logs to see what you’ll include in the next version of your book. Lots of work and thinking.

Another idea for single sourcing a wiki is that the wiki files themselves are the source - if we could invent a DITA wiki where a webform is used to edit DITA topics then we’re there. The wiki platform would also become a publishing engine. Also Confluence appears to work on this idea, that the wiki files are the source and you can publish out to PDF.

Paul Kandel at Intel has this idea that you’d have an offline wiki, with synchronizations every once in a while (you’d set the time parameters). He’s talking about the Dojo Offline Toolkit ( http://dojotoolkit.org/offline), which is based on Google Gears (http://code.google.com/apis/gears/ ), could provide an outstanding solution to the issue of generating offline doc formats. You could enable the wiki itself to be viewed offline, and user additions could automatically synchronize with the online version. I’m not sure I fully understand the advantages and disadvantages here, but the source could be “frozen” in time every once in a while.
Another idea is to be very selective in what you put in a wiki, and make the wiki the source for that selective info only.

Many wiki platforms have import and export capability. However, as my co-worker Mary said on the Author-it users Yahoo group, try not to have your precious content be downstream, meaning, if someone asks you to export all your Author-it topics to Word so that they can be imported into Wikimedia, try to find a way to have the content go the other way around (export Wikimedia content and then import it into Author-it).

I’m also working on the One Laptop Per Child project which is an education project to provide opportunities for children to explore and express themselves. It’s a neat project where we would really like to figure out how to go from wiki content to Author-it and then use Idiom for translation… but it’s probably a “copy from the OLPC Wiki and paste into Author-it” method because the wiki.laptop.org content is not written for the audience we have in mind. The docs for the kids are translated into at least seven languages. It’s an interesting project to be on, and I’m learning so much as I go.

2. You found that with Wikipedia, fewer than 1 percent of users contribute more than half the edits. Should technical writers expect the same 1 percent user contribution effort with the wikis they create?
I just read on keycontent.org that even the MSDN wiki has 5 top contributors. Of the 1876 contributors, 5 contributors (three from Microsoft) made about 1500 of the edits (out of 5800 edits).  I believe you should expect a similar contribution effort as long as those numbers continue to be displayed in other wikis. I suppose the key is recruiting and maintaining relationships with those users. And really, you probably want just a few core inner circle type of people so that you can maintain positive relationships. It’s like an active listserv - you can probably count on one or two hands who the inner circle of contributors are. Those are your experts who are also helpful and giving.

3. If it’s only 1 percent, and your audience is 500 users, that’s only 5 people making edits. Is the wiki even worth it then?

It’s certainly worth it to the 5 contributors who are motivated for whatever reason. And the audience size is difficult to speak to the value - if your manuals had an audience of only 5 people, would you write them anyway? In some cases, yes, because many products need the manual for quality purposes - it’s just an expectation of a software or consumer product. For some products, a wiki is an expectation (probably as an extension of highly visible/visited forums).

I write more about motivations for contributing to wikis in this article on The Content Wrangler. (Think of Reciprocity, Reputation, Efficiency, Attachment to a group).

4. What type of information is a wiki best suited for? Reference? Troubleshooting? Living documents? Why?

I believe that there are several reasons to use a wiki for certain types of information. For Reference information, a wiki is searchable and allows for easy upload of large log files (although if the reference info is in tables, well, I’m not sure how each wiki engine would handle table formatting). Troubleshooting info in a wiki follows the “better than a support forum” model for wiki building. A document that changes often or should change often might be suited for a wiki. Internally, developers can use wikis to explain why the software was designed the way it was, what gotchas in the code to be aware of. Wikis are quick methods for team meeting note-taking and that sort of thing, which would be reference info. So I guess the type of information is the type that people want fast and want to collaborate on.

One person on Gordon McLean’s website onemanwrites said that a wiki plus a Google search appliance is a really good thing. I found that to be the case at BMC for the internal wikis and searching, the combo was killer for finding info or for finding collaborators quickly. That commentor also had the good sense to say “it’s worth watching what goes into it to guard against people setting bad advice in stone.”

5. Is the typical wiki editor robust enough to support all the complicated styling that technical writers do? Can you create your own styles? How hard is it to work with graphics?

Some wiki engines are robust enough… lots of technical writers that I talk to like the Confluence editor’s robustness. I’m not sure if technical writers do much complicated styling really, compared to magazine layouts and glossy brochures. Or if we do need complex styling, the copy is sent to layout.

I’m also not sure how complex tables are in most wiki engines. I think for the most part, you get headings, paragraphs, and lists. Beyond that and levels of those, what else do you need for much technical writing?

Graphics can be a complete bear to get in… apparently one of the Motorola writers had a heckuva time importing the graphics from the user manual into the Mediawiki-based wiki with the time crunch she was up against.

6. Who is actually using a wiki? Have you personally used a wiki successfully for a product?

Many people are using wikis internally. I myself was more interested in wiki use externally for product documentation, and interviewed Emily Kaplan at Motorola and Dee Elling at Borland for information about technical product documentation house in a wiki or wiki-like structure. Harry Miller at Microsoft also interviewed one of the PMs for the MSDN wiki.
Wikis are a favorite quick website set up for many open source-type projects. Also the gaming communities seem to have flocked to wikis either as a replacement or enhancement to customer support or game discussion forums.

I’m using www.imiscommunity.com for my current job, and it’s highly effective for making quick web pages for internal or external use. Plus the search engine is useful. It’s a Drupal site but nearly every page has an Edit tab, so it’s wiki-like.

7. Wikis have been around for 10 years. Wouldn’t they take off if they were going to?
I think they have taken off in certain circles, just not yet in ours. I think that with a set of best practices or push from customers or employers, wikis will be in demand, and it’s a matter of positioning your tech pubs department as the overseers of that content. Without a strong guiding hand, a wiki isn’t that useful because people don’t know what to contribute or how to handle revisions and so forth.

8. What if a user makes a change you don’t like? Do you change it back, offending the contributor? Or do you leave it in, offending the other users? How long do you stick around making these decisions?

I think that you almost need to think of the contributor as a team member, and then behave as you would with a colleague writer. If it’s inaccurate, you change it and reason with the person as to why it has changed. If you’re looking to save time, or don’t have the time to arbitrate, then don’t take long to make those decisions, or don’t get involved with that particular change. But don’t expect to build a wiki and have all these contributions come for free or little resource or time investment. That’s just not realistic.

9. How does a wiki build community?

In itself, a wiki can’t build community. There’s a great quote from Wiki for Dummies with a heading entitled something like “don’t go on a wiki suicide mission.” It says “Wikis don’t have magical powers. They cannot create camaraderie where none exists, nor can they streamline an out-of-control operation. They are not powerful information magnets, nor will they make your team better writers, more organized, or more intelligent. In short, without a strong guiding hand, wikis are useless.

Wikis cannot promise instant returns or unbelievable creativity. Wikis allow users to quickly and easily update and upload information.“

I enjoyed the heck out of that quote. But, many web workers are finding that a wiki is a place to find other like-minded individuals trying to tackle the same problems and offering similar solutions, much like a customer support forum. So a wiki can help build community by offering information and identity to the contributors.

10. As a technical writer, are you ever done with a wiki project?

I’d say No. Wiki building is a lot more about relationships and connections so you’d never want to sever those ties if there’s still a bond there. Anyone who thinks that starting a wiki will make less work for their techpubs team by crowdsourcing the writing is fooling themselves. But if you want to serve and connect with a certain set of customers, you’ll do what it takes to keep the wiki alive and kicking.

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.

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.

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.