|Acrolinx Server||5.1, 5.2|
|If you have an earlier server version, you can download an archived version of this article here .|
The guidance wizard takes you through the process of fine-tuning your writing guidance. Writing guidance includes your style and grammar guidelines as well as guidance on how to use particular words. You can fine-tune how your guidelines work and add words to your terminology database or spelling dictionary.
The guidance wizard works best when your writers have already been using Acrolinx for a while. Before you can fine-tune your writing guidance, you need to know what's working and what isn't working. For example, some teams get started quickly by rolling out Acrolinx with a standard set of style and grammar guidelines. After a while, the team leader gets an idea of the issues that Acrolinx keeps finding in their content. These issues could be genuine quality issues, or they could be related to guidelines that aren't compatible with the company style. The team leader can then decide to disable or fine-tune the incompatible guidelines.
Let's take a closer look at how the guidance wizard works:
Have You Checked Enough Content?
If you log on to the Dashboard, you'll find the guidance wizard in the Guidance Settings section.
First off, Acrolinx will tell you if it has enough information to help you. If your team hasn't been using Acrolinx much, the guidance wizard won't be able to help. You need to check a decent volume of content so that Acrolinx is familiar with your content and can help you fine-tune your guidance.
We recommend that your writers check at least 1,000 words in total (about 4 pages), but you can start working as soon as Acrolinx has collected one or more content issues.
Choose What Type of Guidance to Work On
Let's assume you've checked enough content. The next step is to choose what to work on. You can update your style and grammar guidance or you can update your word guidance. By the way, when we say "word guidance" we mean any guidelines that you have about specific words. How to spell them, when to use them, and when not to use them. Acrolinx provides a custom spelling dictionary and terminology database to help you implement your word guidance.
Click one of the two options:
- Fine-tune word guidance
- Fine-tune style and grammar guidance
Updating Your Word Guidance
Let's start with word guidance. You probably have a list of words that are important to your brand and you want your writers to use them consistently. Product names are an obvious example. These are often words that a normal spell checker might report as a spelling issue. These spell checkers usually let you add words to a custom dictionary, and Acrolinx is no different. But a dictionary isn't always the best place for these words.
Words That Belong in Your Terminology Database
Let's say have a product line called "SmartTech®". Sure, you don't want this word to come up as a spelling issue but it's more than that. The word is also part of your brand language. You want all writers to write it exactly the same way. It's not "Smarttech", or "Smart-tech" - it's "SmartTech®". You want complete control over that word. That's when you add a word to your terminology.
Words That Belong in Your Custom Dictionary
On the other hand, you might have a proper noun that also keeps showing up as a spelling issue. For example, suppose you're writing about Dysnomia, the Greek goddess of lawlessness and the name of a moon which orbits the dwarf planet "Eris". Acrolinx will probably mark "Dysnomia" and "Eris" as spelling issues. These words aren't really part of your company terminology but you don't want them to keep coming up as spelling issues either. That's when you add a word to your spelling dictionary.
The Word Guidance Page
The word guidance page shows you words that frequently occur in your content, but are "unknown" because they don't appear in any standard dictionary. You can then decide whether to add them to your custom dictionary or to your terminology.
When you first open this page, you'll see a list of words with three possible "Actions" for each word. Acrolinx suggests an action for each word. You can see what actions Acrolinx has suggested because the corresponding icons are already highlighted blue. We call these preselected actions the "default action". If you agree with the default action, you just need to confirm the decision. If not, you can change the action.
You have the following choices for each word:
Add the word as a preferred term
Confirm that the word is part of your company terminology. It will be added to your terminology database so that you can manage the term settings and translations.
Add the word to your dictionary
Confirm that the word is spelled properly. It will be added your company dictionary so that Acrolinx stops reporting it as a spelling issue.
Mark as a spelling issue
Confirm that the word is a genuine spelling issue and continue reporting it to writers.
To update your word guidance, follow these steps:
Review the default actions for each word and confirm the actions that you're happy with.
Select the Confirmed checkbox next to each word.
You can also select batches of words in the follow ways.
- Click SELECT ALL ON THIS PAGE to select only the words on the current page.
- Open the dropdown and click Select All Words on All Pages or if you want to cancel your selection, click Deselect All Words on All Pages .
If you want to hide the words that you've confirmed already, select the Hide confirmed words option.
Update the words that need a different action.
Click your preferred action. If you change the action, Acrolinx automatically marks the word as Confirmed for you.
If you're not sure about a word, try looking at examples of how writers have used the word.
There are two ways to do this:
To see one usage example, move your mouse over the word. In the help section, you'll see one example sentence where Acrolinx found the word.
To see all sentences where Acrolinx found this word, click the word.
In usage examples window that appears, you can review all the ways in which your writers have used this word.
- To see one usage example, move your mouse over the word. In the help section, you'll see one example sentence where Acrolinx found the word.
When you've confirmed enough words, click
Acrolinx then applies your changes and all words that are marked as confirmed are removed from the Word Guidance page.
What Happens to the Words That You've Confirmed?
Acrolinx applies your changes with the following results:
Words that you categorized as new terms are added to your terminology database as "preferred" terms and are put in a default domain.
However, you'll need to reload your language configuration to ensure that Acrolinx stops treating these words as spelling issues.
Words that you categorized as dictionary entries are added to a company-wide dictionary.
This change takes effect straight away. Bear in mind that this company-wide dictionary is different from the custom dictionaries that writers update from the plug-ins. Those dictionaries are specific to certain user accounts, documents, or writing guides. Your company-wide dictionary applies to everyone who uses Acrolinx and can only be updated in the guidance wizard.
Words that you categorized as genuine spelling issues as saved on your Acrolinx server.
This change also takes effect straight away. Acrolinx remembers that you've confirmed this word is a genuine spelling issue and won't show it to you again in the guidance wizard. Acrolinx will still report this word as a spelling issue to writers when they check their content.
Fine-tuning Your Style and Grammar Guidance
Most people have different style guides for different departments and styles of writing. In Acrolinx, each style guide is reflected as a writing guide. When you fine-tune your style and grammar guidance, you start by selecting the writing guide that you want to fine-tune.
In the second step of the guidance wizard, click Fine-tune the guidelines in "<Writing Guide Name>" .
Once you open the guidelines page for your selected writing guide, you'll see a list of the guidelines that cause the most issues for your writers. You can then decide what to do with each guideline.
Unlike word guidance, the guidance wizard doesn't suggest what to do with each style or grammar guideline. Instead, you'll see the list of the guidelines sorted by the guidelines that cause the most issues for your writers. You'll see the action that is currently configured for the guideline. If you've just installed Acrolinx, the selected actions are the system defaults. Otherwise, these actions will be the actions that you selected the last time you used the guidance wizard or guideline configuration page.
To fine-tune your style and grammar guidance, follow these steps:
Review the current action for each guideline, look at the usage examples, and if necessary, update the guidelines that need a different action.
You have the following actions for each guideline:
- Turn off the guideline completely.
- Turn on the guideline.
Make this guideline apply only to certain contexts within your document structure.
If you don't know much about context-specific checking, we recommend that you read the article " configuring guidelines to be context-specific ".
Guidelines that relate to the length of a sentence or paragraph have one extra choice:
- Change the word or sentence limit that's defined in the guideline.
If you want to change the limit for a guideline that controls the sentence or paragraph length, click the configure button
In the windows that appears, you can enter the new limit. To help you with your decision, Acrolinx shows you some statistics on the distribution of sentence or paragraph lengths in your content.
The vertical axis shows the number of occurrences and the horizontal access shows the different lengths that Acrolinx detected.
If you're not sure about a guideline, try looking at examples of where the guideline caused an issue.
There are two ways to do this:
To see one usage example, move your mouse over the guideline. In the help section, you'll see one example sentence where Acrolinx found the word.
To see all sentences where the guideline caused an issue, click the guideline.
In usage examples window that appears, you can review all the ways in which your writers broke the guideline.
In many cases, the issues might be due to other Acrolinx settings such as filter and segmentation settings. You can then go back to the writers and help them with these settings.
What do the little gray and blue tags mean?
Those tags indicate where Acrolinx found the sentence in the document structure.
The gray tags represent the actual elements of the document. For example, in an HTML document, the sentence might be in "
p > table > p." The blue tags are extra tags that Acrolinx has added. Acrolinx uses these extra tags to categorize different contexts. This categorization is important for context-sensitive guidelines. For example, certain contexts can have different guidelines for how long a sentence should be. Sentences in titles should generally be much shorter than sentences in paragraphs. Context-sensitive guidelines kick in when a context tag matches the tag that's defined in the guideline.
- To see one usage example, move your mouse over the guideline. In the help section, you'll see one example sentence where Acrolinx found the word.
When you've processed enough guidelines, click
If you haven't changed anything, click Apply Changes anyway to confirm that everything is fine.
The guidance wizard then applies your changes and you're taken back to the second page so that you can see what steps are remaining.