Configure How Acrolinx Scores Are Calculated

When you check with an Acrolinx Integration, you receive an Acrolinx Score for the content. The Acrolinx Score expresses the average of all category scores as a standardized score out of 100 that is easier for most users to understand. The higher the score, the higher the quality of the content. You can influence the calculation of the Acrolinx Score by configuring the weighting of category scores.

How the Acrolinx Score Is Calculated

Content scores help you to quantify the quality of a document and compare it with other documents. The Acrolinx Score expresses the overall quality of your content as a score between 1 and 100. You also get similar scores for how well you did in each of the quality categories such as spelling or style. The overall Acrolinx Score is simply an average of your individual category scores.

How the Scores for Each Quality Category Are Calculated

Each individual quality category is calculated according to the following formula:

Normalized document length / (Normalized document length + issue count)

This formula contains the following variables:

  • Document length

    The number of words in the document.

  • Normalized document length

    The number of words in the document divided by a factor of 75.

  • Issue count

    The number of issues that Acrolinx found in the quality category, such as spelling.


The following table shows you what the calculation steps would be for a document with 1000 words and 12 spelling issues.

StepCalculationResult
Calculate the normalized document length1000 / 7513.33
Add the normalized document length and the issue count13.33 + 1225.33
Divide the normalized document length by the result of the previous step13.33 / 25.330.5263
Express the result as a percentage and round it to the nearest whole number0.5263 * 10053

Calculating the Overall Acrolinx Score

The Acrolinx Score is the average of all the category scores rounded down to the nearest whole number. For example, suppose that you check a document, open your Scorecard, and see the following scores:

CategoryScore
Terminology57
Spelling71
Grammar71
Style33

If you take the average of all the category scores and round it down to the nearest whole number, you get a final Acrolinx Score of 58.

Weighting the Category Scores

You can configure Acrolinx to increase or decrease the influence that a category score has on the Acrolinx Score. Weighting a category score helps writers prioritize the issues to correct in a document.

For example, suppose that want to encourage writers to remove all spelling issues in their content before addressing other issues. You set the weighting for the spelling category to 200%.

This way, the spelling category score counts twice as much as the same number of issues in any other category.

To configure the weighting for a category score, follow these steps:

  1. Open the following file: thresholds.xml

    You can find this file in the following location:

    <INSTALL_DIR>\server\www\xsl
  2. Edit the projectThreshold element:

    <projectThreshold yellowQuality="80" redQuality="60" styleWeight="100" grammarWeight="100" termsWeight="100" admitTermsWeight="50" spellingWeight="150" reuseWeight="100" voiceGuidanceWeight="100"/>

    Enter a new weighting value for one or more of the category weight attributes.

    For example, to change the weighting for spelling, update the value for the attribute spellingWeight.

    All voice categories share the same weight setting: voiceGuidanceWeight.
  3. Save your changes and restart the core server.


 Advanced Topics

Configuring the Colors for the Acrolinx Score and Category Scores

The Acrolinx Scorecard displays the Acrolinx Score and the category scores with colored bars. These colors reflect the range of acceptability of the Acrolinx Score and the category scores respectively.

The Acrolinx Score and the category scores can have one of three colors:

  • Green - excellent
  • Yellow - acceptable
  • Red - unacceptable

The category score colors appear underneath the Acrolinx Score on the Scorecard.

You can use color thresholds to configure the minimum Acrolinx Score or category score that a document must reach before a specific color is displayed.

To configure the colors for the quality and category scores, follow these steps:

  1. Open the following file: thresholds.xml

    You can find this file in the following location:

    <INSTALL_DIR>\server\www\xsl
  2. To change the color for the Acrolinx Score, edit the projectThreshold element.

    It should look something like this:

    <projectThreshold
    yellowQuality = "80"
    redQuality = "60"
    
    styleWeight="100"
    grammarWeight="100"
    termsWeight="100" 
    termsAdmittedWeight="50" 
    spellingWeight="100"
    reuseWeight="100"
    voiceGuidanceWeight="100"
    />

    Update the following attributes:

    redQuality="<THRESHOLD>" yellowQuality="<THRESHOLD>"

    Enter a new Acrolinx Score threshold for the yellowQuality and redQuality attributes.

    The color changes when the scores are lower than the specified threshold. If the Acrolinx Score is equal to, or higher than the yellow threshold, the Acrolinx Score color defaults to green.

    For example, suppose that you wanted Acrolinx Scores lower than 10 to show up as red, and scores that are lower than 50 to show up as yellow. In this case, you would configure the projectThreshold element as follows:

    <projectThreshold
    yellowQuality = "50"
    redQuality = "10"
    
    styleWeight="100"
    grammarWeight="100"
    termsWeight="100" 
    termsAdmittedWeight="50" 
    spellingWeight="100"
    reuseWeight="100"
    voiceGuidanceWeight="100"
    />
        
  3. To change the color for a category score, edit one or more of the elements with the naming convention <CATEGORY_NAME>Threshold. For example, you would update the spellingThreshold element as follows.

    <spellingThreshold yellowQuality="60" redQuality="40"/>
    All voice categories share the same weight setting: voiceGuidanceWeight.
  4. Save your changes and restart the core server.