Defining your needs and constraints
Needs and constraints can relate to the potential users of the tool and/or to the documentation production process.
These questions and topics can help you define your needs.
Are they writers, editors, or translators?
The needs and constraints of each group may differ. For example, if your writers work in a language other than English, they will not need an authoring aid for STE. But your translators will perhaps want to parse their texts through a checker.
Are they language-sensitive?
Are they interested in word choice and writing style? Do they have some knowledge of grammar?
Not all writers are language sensitive. Some focus only on the technical aspects of their subject, and some may feel uncomfortable if they have to be critical of their writing. In such cases, writers are likely to use a rule checker without discernment. If you really wish to use a rule checker in this context, consider having an editor run the checker instead of the writer.
Is English their native language?
If not, do they need help with English grammar and style in addition to ASD-STE100 rules and vocabulary?
Make sure that the tool you select offers support tailored to the writers’ native language. Even if it does, it is advisable to have final draft texts reviewed by a human editor. Grammar and style checkers can help with common errors, but they may not offer adequate guidance for less frequent or more complex issues.
Will they accept the constraints involved in using a checker - especially a rule checker?
These constraints include the time needed for checking, correcting, and reviewing. Language-sensitive writers are often willing to accept these constraints. Others may not want to spend time considering error messages or revising their text.
Possible solutions:
- Split the editing: writers check the rules they are comfortable with, editors manage the rest.
- Assign all checking to the editor.
In both cases, writers must have final approval of the edited text, as they are responsible for its content.
What type of assistance do they require?
If writers use a rule checker, will the editor need the same tool, or would a look-up tool be sufficient?
Is the tool compatible with your documentation system or platform?
Is the response time satisfactory?
What features does the tool offer?
Can the checker process formatting information (for example, XML tags) to determine which text should be checked?
What kind of user support is provided with the tool?
Does the supplier provide training for the tool?
Is the tool configured for ASD-STE100?
Some tools can be configured for ASD-STE100 but also for other controlled English variants. Make sure that the tool you are interested in is configured specifically for STE, and that any extra rules or words that the tool contains are not in contradiction with the standard.
Which STE rules does the checker verify?
Not all STE rules can be checked automatically. For example, a checker cannot determine whether the first sentence in a paragraph is the topic sentence. But a checker should be able to check sentence length, overlong multi-word nouns, and passive voice. Some tools may also attempt to check for the correct meaning of certain STE approved words.
What is the degree of accuracy of the error messages?
There are several reasons for unsatisfactory messages:
- Poor linguistic analysis (tool limitation)
- Formatting issues in the source text (for example, carriage returns in the middle of sentences, unwanted spaces, text in parentheses in the middle of a sentence)
- Source text complexity (for example, tables, overly complex sentences).
What is the rate of “noise”?
Noise refers to unwanted messages, such as “missing article” when an article is not appropriate.
Is the error message wording clear?
Messages should be understandable to the widest possible range of users.
Is the vocabulary database easy to update?
This applies to your technical nouns, technical verbs, and extra unapproved words. The ease of updating will determine how much linguistic knowledge the administrator will need.
Can the checker distinguish between procedural and descriptive text?
Some rules differ between these two text types.
Does the checker generate a report file?
Reports can be valuable for editors or system administrators.