The screenshot below illustrates the character tag Comment-text applied to editorial notes.

Further reading

If you need help creating a new character tag in FrameMaker, refer to "Character Formats" in FrameMaker web Help. To understand how to apply and manage conditional tags, see "Working in conditional documents".

Click here for step by step instructions on how to create specialized DITA DTDs, derive EDDs for use in FrameMaker, create a complete structured application, and use the specialized DITA DTDs to author content in FrameMaker.

This where AuthorAssistant comes in. It is meant to improve the quality, consistency and translatability of technical content. And it comes free with FrameMaker 9!

You can configure AuthorAssistant to check for correct term usage, passive voice, future tense, and standardize frequently used acronyms. You can also check for wordiness, lengthy sentences, deprecated terms, misused words, and other style checks.

AuthorAssistant can also check against previously translated content, so that you can improve content reuse and reduce the downstream costs of localizing content.

Download AuthorAssistant

The AuthorAssistant comes free with FrameMaker 9 and Adobe Technical Communication Suite 2.0. You can download the AuthorAssistant plug-in (GAMS-2008-SP3-FRAME-192.exe) from:
http://www.adobe.com/support/downloads/detail.jsp?ftpID=4357

This page also lists the system requirements, installation instructions, and the licensing agreement.

Once you have downloaded and installed the AuthorAssistant plug-in a menu option, SDLAuthorAssistant, is added to the FrameMaker 9 menu bar. This menu option appears only when you’re in the Document view as opposed to the Resource Manager view (book window).

An icon is also added to the Windows system tray. You can configure the server setup, cache files from the server, and set up synchronization schedules from the system tray menu.

Import and export profile settings

The next step is to configure all the checks in AuthorAssistant. This includes setting up the term bank, configuring the rule checks – these can be company-wide as well as product specific ones. Once you have configured all the checks, you can extract the settings into a profile and distribute this profile for a consistent setup.

• Click Export on the General tab to export all the settings in a .pfl file.
• Click the Import button in the General tab and specify the .pfl file that contains the settings. This configures a new desktop with your rule check settings.

Configuring AuthorAssistant

The first step is to configure AuthorAssistant for your customizations. Set up the plug-in for the following:

Terminology Checks
• check the document for the presence of forbidden terms
• comparing document text to terminology data held in a local or a server-based termbase

Style and Linguistic Checks
• incorporates a default set of grammar and linguistic checks
• create style guides and rules of your own and add these to the check

Translation Memory Checks
• check documents for presence of sentences that closely match sentences from previously translated documents (require access to trans memories)
• reuse the previously translated sentences

General workflow

Configuring style checks

View image - Style Check dialog

Spelling variations

You can choose from British English and American English.

Abbreviations

You can specify the list of abbreviations AuthorAssistant should check for and their corresponding full form. You can set up AuthorAssistant to replace either the full form with the abbreviated version or the abbreviated version with the full form.

For example, replace all occurrences of Fm, FM, or fm with FrameMaker. You can set up as many abbreviation-full-form pairs as required. To speed up this, just create a simple text file with tab delimited values and import it to populate this tab.

View image - Abbreviations text file

Punctuation

AuthorAssistant already provides the following list of common punctuation rule checks. Select the ones that apply.

View image - Punctuation options

Length of sentence

Simply specify the minimum word count and the maximum permitted word count for a sentence. For example, if you specify 30 as the max word count then AuthorAssistant will highlight all sentences above 30 words for the author to correct.

View image - Sentence length

Misused words

Specify a list of misused words or deprecated terms and the approved alternatives for the same. Here you can have a simple list of words and a description of why these are discouraged.

For example, palette could be a deprecated term to be replaced by panel throughout documentation.
Specifying the preferred term double square brackets [[ ]] lets the writer quickly replace the word without typing it out during the check.

Again you can import a text file containing pairs of misused words and their preferred alternatives.

View image - Misused words example

Do not allow contractions

Select the checkbox if contractions, such as don’t, can’t, haven’t, you’ve, are discouraged according to your style guide.

Compound words

Specify a list of incorrect compound words and the prescribed alternatives.

Wordiness

Specify wordy phrases that should be avoided and the recommended alternatives to them. For example, replace ‘in order to’ with ‘to’. Again you can set these pairs up in a text file and import the same into AuthorAssistant.

User-defined rules

This list can include anything that you would like AuthorAssistant to correct. For example, use ‘and’ instead of ‘&’.

Linguistic checks

Specify settings for linguistic checks, such as passive voice, future tense, dangling modifiers, or noun and verb forms.

View image - Linguistic Checks dialog

Checking a document

You can opt to check an open document or a selection in the open document. For closed documents you can generate a report for a single or multiple documents and make the corrections later.

Click SDLAuthorAssistant -> Check text to begin checking a document.

All suggested corrections are displayed in a separate dockable window, SDL AuthorAssistant Results. It displays the source sentence with the erroneous words in red in an editable text box. The bottom half of the window displays the reason for the error and possible alternatives.

View image - Results window

You can:
• Accept suggested alternatives if any
• Type a correction and click Apply to change the sentence in the document
• Revert any changes
• Recheck the changes you make before applying them
• Apply changes to the next similar error

After correcting a sentence, move onto the next error in the document.

Batch processing multiple documents

You can obtain reports for multiple documents in one go. For example, if you want to generate a report for all the files in a book, just follow these steps:

1. Click SDLAuthorAssistant -> Create Reports From Files
2. Select the options and click OK.
3. Select multiple files and click Open.
4. Specify a report name and click Save.

You can select a mix of .fm and .xml files for the reports. To display .xml files, select All Files from the Files Of Type list box. You can’t select a .book file though. If you do, AuthorAssistant will ignore it and process the remaining files.

AuthorAssistant generates the report in an HTML format and opens it in the default browser.

Report format

The report generated by AuthorAssistant has the following sections:

• Metadata for the report, such as the time it was generated, number of files checked, and the author name.
• A cumulative summary of total errors categorized by the error type in the selected files.
• File names in case you have generated the report for multiple files. You can click each link to see the list of errors categorized by the error type.
• Each error category also shows the exact error and the instances of each in the document.
• The last section summarizes the settings that were enabled and disabled when the report was run, details of translation memories, and termbases used.

View image - Sample report

-----------------------------------------------------------------------------------------------------------------------------

Click here for Adobe FrameMaker 9 documentation.

TCS 2 puts great emphasis on integration. Along with Adobe Captivate 4, FrameMaker 9, RoboHelp 8 and Acrobat Professional Extended 9, it includes Adobe Photoshop CS4 in recognition of the fact that it isn't just words that technical communicators deal in. And instead of being disjoint pieces of a puzzle, these components talk with one another as constituents of a platform. In particular, I am excited about the enhancements in FM-RH integration that enable you to author content once in FM and output it seamlessly in multiple formats using RH.

Another new workflow that I find very useful makes iterative shared review cycles less painful. You can now generate tagged PDFs from your FM files specifically for review, and once the reviewers are through with their bit of the carnage, you can import the Acrobat PDF comments back into the source FM document and decide what to do with them. This workflow has translated into hours of effort savings for me, as I hope it will for you.

Also worth more than an honorable mention is the new Adobe AIR Help format that enables true Web 2.0-age documentation. Users can now comment on online Help content in real time, suggesting enhancements, highlighting bugs, or simply adding a tip or two. Thus, instead of being static content that is 'updated' once in a while, documentation becomes a living, growing body of information, supported by the weight of an entire community. The documentation for TCS 2 itself is delivered as Adobe AIR Help. So you can go ahead right away and check out the power of this new format.

That is, of course, not all. More than anything else, I find TCS 2 notable for the way it brings together the leading content formats on the Web. There is plenty of dope to help you add interactivity, color and motion to your technical communications. Read more about the top new features of Adobe TCS 2 here.

Now that TCS 2 has reached you, the technical communicators that it was designed for, we look forward to suggestions and experiences. And yes, do keep coming to this blog as we share tidbits and tips to help you make the most of the flexibility that this suite has to offer.

Happy writing, then!