Automating style checks using SDL AuthorAssistant


SDL AuthorAssistant is a quality assurance tool for documentation. AuthorAssistant checks documents for corporate writing styles and standards as well as standard spelling and grammar. You can automate most of your style guide rule checks and linguistic checks using AuthorAssistant.


Automating style checks helps when you don’t have the resources (editors) to review all the documents or the calendar time to squeeze in editorial review rounds before your final doc freeze. Having said that, even with a constant increase in the number of things an editor needs to remember, it’s a tough to do a air-tight editorial in shorter timelines. Especially if you have a huge number of style checks and multiple word lists, some may be company specific, some specific to the product suite, and some specific to the product itself. Having an automated style checker can greatly reduce the number of misses and provide consistency across product documentation sets, across cross-geog writer teams, or when you have multiple writers working on the same book or document.

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
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.