The Guidance Wizard

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

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

Click START or CONTINUE to go to the next step.

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 terminology database and spelling exception list 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 as spelling exceptions, and Acrolinx is no different. But a list of spelling exceptions isn't always the best place for these words.

Words That Belong in Your Terminology Database

Let's say you have a product line called "AwesomeThing®". 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 "Awesomething", or "Awesome-thing" - it's "AwesomeThing®". You want complete control over that word. That's when you add a word to your terminology.

Words That Belong in Your Spelling Exception List

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

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 as a spelling exception 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.

  • Confirm spelling

    Confirm that the word is spelled correctly. It'll be added as a permanent spelling exception 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:

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

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

  3. 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.
  4. When you've confirmed enough words, click Apply Changes.
    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 discovered 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 spelling exceptions are added to a company-wide spelling exception list.

    This change takes effect straight away. Bear in mind that this company-wide spelling exception list is different from the custom spelling exception lists that writers update from the integrations. Those spelling exceptions can be specific to certain documents or Guidance Profiles. Your company-wide spelling exception list 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 Core Platform.

    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:

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

    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.
  2. If you want to change the limit for a guideline that controls the sentence or paragraph length, click the configure button .

    In the window 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.

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

  4. Click Apply Changes to save your changes.

    If you haven't changed anything, click Back to return to the overview page.