[Ed. Note: This is the second of a two-part list of tips for using the editorial tool Acrolinx.]
Encourage writers to submit issues and suggestions
Due to the complexity of the English language, Acrolinx is going to have false positives. For example, the tool might misread “…the two menus, View and Edit.” as a list of three items and recommend inserting a serial comma after View. In situations like these, it’s critical that writers can submit these issues to the Acrolinx team as easily as possible.
Create an email address for your Acrolinx team and encourage writers to send in their issues and suggestions. Also consider customizing the Acrolinx flag reports so that writers can email the team directly from the reports.
The writers are your ears on the ground, so encourage them to send false positives whenever they encounter them. You can’t improve Acrolinx if you don’t know what’s broken.
Customize the rules to match your styleAcrolinx ships with a common set of rules that apply to large swaths of documentation. But these rules don’t cover everything. Customization is the key to making Acrolinx work for you. Go through your style guide and add in those clear-cut rules that Acrolinx handles so well, such as ones for hyphenation, capitalization, and bulleted lists.
To further customize Acrolinx, you can apply rules only to certain XML elements. For example, if your style is to write
<heading1> elements in Book Title Case but
<heading2> elements in Sentence case, Acrolinx can check for that.
You can also turn off rules where the rules of English don’t apply. Suppose you have an element that lists a summary of valid values:
<values>on | off</values>
You can have Acrolinx ignore content found in these tags. This feature works for inline elements as well. Take the sentence “Open the
</label> menu.” You can have Acrolinx skip over the
<label> menu so that the tool doesn’t mistakenly misread View as a verb.
Rewrite the Acrolinx help to use your own examples
For each flag you receive, Acrolinx provides the rule associated with the flag, plus a few generic example sentences. For example, here are a few example sentences from the “uncountable noun” rule:
Incorrect: An information is available at the company website.
Correct: Information is available at the company website.
To better meet the needs of your writers, replace these general sentences with relevant, domain-specific ones instead. Writers are more likely to internalize the Acrolinx rules when the examples match what they see in their own documentation.
Explore advanced features
Other Acrolinx features include a terminology checker, which can further enhance consistency and reduce translation costs. You can also use it make more domain-specific word lists that run only on subsets of your documentation. Acrolinx is only as effective as the amount of effort you put into it, so it pays to take advantage of its advanced tools.
About the Author
Will Tripp is a technical editor at MathWorks in Natick, MA. Will has a BA in English from the University of New Hampshire, an MA in Writing and Publishing from Emerson College, and a certificate in Technical Writing from Middlesex Community College. He has more than 15 years of professional writing and editing experience.