AuthorIT

Question:  Do you create print (PDF ready for print) output? If you do, how well does it work? That's the biggest down side I've heard about AIT.

Answer:    Yes, I do create print output. I have install guides that go to PDF only, and I have user's guides (that combine the online help and install guide into a single book). Yes, I have to output THROUGH Word to get to the PDF. But AIT is very strict about adherence to styles and that, along with the knowledge the AIT devs have of the Word "issues" with creating large manuals, ensures that I have minimal problems once I get the docs into Word.

Word on the street is that AuthorIT version 5 will contain direct publish to PDF.

[from another source...] For PDF, you publish to Word (and it's always a 'clean' publication, so the numbers etc. always work!), then create a PDF from the Word doc. I do about 4x 500 page manuals and it takes minutes. In AIT, Word doesn't corrupt like it does when you're authoring in Word because it always creates the Word doc 'from scratch' at publishing time. In v5 (coming...) there is meant to be a direct to PDF option (I think using XSL-FO).

Question:  What "flavors" of online help and HTML-based output does it create?

Answer:    HTML Help, HTML-based help, WinHelp, JavaHelp, and Oracle Help.

[from another source...] WinHelp, CHMs, pure HTML, pure XHTML (both with TOCs and Indexes and optional search), JavaHelp and Oracle Help.

Question:  I notice that the TOC and index of the User Guide are not links. Can it create links for these?

Answer:    The TOC can be hyperlinked but the index cannot (this is a limitation of Word).

Question:  Can you create a two-level index?

Answer:    Yes, and I do. I can also easily create see also references.

[from another source...] TOC links are created automaitcally if you have your Word template set up to do this; Word does NOT create links for index entries.

With regard to a 2-level index - I guess you're referring to main entries and sub-entries... Yes; if you wanted to go to 5 levels, you could (but you'd REALLY have to decide if this would create a usable index!)

Question:  Is there conditional text?

Answer:    I'm not sure what you mean by conditional text. (It's likely that someone didn't update the index before they output to PDF and that's why the page numbers differ?) At any rate, do you mean what's known as variables? You can create a variable and then assign it to each book or topic. For example, I have several different products that I document; I've created variables to handle the product names, product components, version numbers, and so on. Is that what you mean? I can also set topics so that they output to online only, or that they are included in the online help but not the TOC (for example, for a context-sensitive topic on a dialog box, where I'll have a "How To" link for the procedural steps).

[another person weighs in...] I have also used AuthorIT for several years and have had the same pleasant experience as Sue. You can do conditional text:

  1. Mark the topic to appear in Help only or print only, etc.
  2. OR share text between topics.

[from another person] You can also conditionalise based on styles. For example, I include screen shots in the print output, but not the online (with a few minor exceptions). For each screen shot, I apply a paragraph style that only publishes in Word output, not in HTML output. Equally, you could set up character styles for text that is ONLY in Word or ONLY in HTML.

I also love the way AuthorIT uses object templates. This makes changes so easy and quick.

Of all the HAT tools out there, I think AuthorIT has the greatest potential to provide a good transition to Longhorn Help too. Every other tool I know, besides AuthorIT, starts with one format (Word, .HTML, or rich text) and then switches to a different format for the outputs. Any time a HAT uses that sort of workflow, I think there are inherent problems. AuthorIT is really format-independent and the only HAT that can claim that, IMHO.

I am not familiar with FrameMaker at all... but sharing text between objects can be accomplished by embedding Topic Objects into other Topic Objects (or not).

You can choose to have Topic Objects appear in only specified output types (say... only HTML, not Print) - with a simple click of a checkbox, and you can choose to assemble Books using particular topics... or not, depending on the product line requirements.

Text within a topic can be conditional using variables such as <product_name> <product_version> <product_build> etc. This is a PERFECT example of the use of variables in AuthorIT. And they are super-easy to assign and apply. Variable types include:

  • Text (a string of any characters up to 2000 characters long)
  • List of Values (a list of pre-set character strings, each up to 255 characters long)
  • File Objects (logos, graphics, etc.)
  • System (time, date, current user).

You can nest variables too... for example, you could include the following variable (which includes nested variables) in your content:

<AITfull_version> = <AITversion>.<AITsubver>.<AITbuild_no> Content could look like: "... the curernt version of Authorit is <AITfull_version>..." Output could look like: "... the current version of AuthorIT is 4.1.0473..." (though perhaps only the "build" component changed)

Question:  What are HTML variables?

HTML variables are variables that are used in HTML output (including .chm's and within JavaScript). You use a custom HTML template to insert the variable. An example would be to customize a doc set so you have the same basic look, but change the name of each to reflect the product name. You could create an HTML variable for the product name, and assign the variable before you publish.

[another person weights in on HTML variables...] In addition to what Sue just said, you can also use variables in a custom HTML template to set up feedback loops extracting topic IDs, version numbers, topic titles etc.

Actually "HTML variables" aren't a different type of variable - they are a standard AIT variable; when used in HTML code (or ASP, JS, or whatever) they have a different syntax from a variable in the main AIT authoring environment.

[more on conditional text...] Conditional text can be one word or a whole section. You highlight what you want to conditionalize and then select the condition from the dialog box.