What you need to know about ISO Schematron| The technical writer version

While working on your technical writing project you might have come across a warning message in your XML editor which gives you some validation check.

Chances are there that upon exploring further you might have learned that these are errors set by your DITA architects. 

So what are these errors anyways which shows up in your XML editor? 

Why these validation checks are actually required in the first place. 

Read this article to have a basic understanding of the ISO Schematron errors that you need to know as a technical writer.

What is ISO Shecmatron?

Schematron is basically a language written in XML (using XPath) that helps to perform a validation check and return results in the form of (error) messages to notify the technical writer.

This message actually notifies the writer and make them aware of some common mistakes in the write-up.

DID YOU KNOW

The Schematron was invented by Rick Jelliffe in 1999 which is an ISO standard. Hence, it is called ISO Schematron.

Some use cases of ISO Schematron

The ISO Schematron is configured by your DITA administrator or DITA Architect for your XML writing tool such as Oxygen, Arbortext editor, XMetaL, etc. 

The errors are highlighted with an underline. When an underlined text is clicked, the corresponding error message is shown in the editor. Some use cases of ISO Schematron are as follows:

1. A semicolon in a short description tag is not allowed.

If in case the technical writer by mistake adds a semi-colon instead of a period, the ISO Schematron detects this anomaly and throws up a warning message. 

2. Avoid using the word “since” in the writing.

This error is subjective on an organization basis. Some organization can use the word “Since” some prefers not to in their documentation. 

In the above case, the ISO Schematron is configured not to allow the “since” word anywhere in the document. Hence when it finds the “since” word, it throws an error. 

The error message also gives suggestions to replace “since” with “because” as the usage of "because" makes it clear that you are talking about cause and effect, "since" usage can imply the passage of time, especially for a global audience.

3. Listing only one item under the list item tag is not allowed.

This basic validation check when configured in the ISO Schematron helps to identify this type of invisible error with ease. 

If you have only one item then you should choose a “para” tag instead of “unordered” or “order” list. 

The above image shows only unordered lists but its equally true for ordered lists too.

4. Avoid using “in order to”.

Again this is a subjective error. Some organization prefers not to use “in order to” in their documentation.

You are overwriting when you are using “in order to”. Instead, you can use “to” for a perfect substitute. Check out that the statement gives a similar meaning when you use “to”.

Completeness check vs ISO Schematron

There are different kinds of validation that can be set using the schemas such as document type definition (DTD), XML Schema Definition (XSD), and Relax NG (RNG).

For example specifying the usage cmd tag in only task topic, defining a template structure of a concept topic, proper hyperlinking is established, etc.

But this document type definitions set up cannot help the writer in avoiding some common errors like using a colon the short description or suppose identifying any overwriting.

This is where the ISO Schematron comes into the picture. 

The DITA architect carefully defines the expected scenario of errors and defines a corresponding message to display if these errors are encountered.

Benefits of using the ISO Schematron

1. The use of the ISO Schematron allows the data architect to add custom rules specific to the projects.

2. Reduce the burden on the writer by saving time to find some basic errors.

3. It helps the writer to achieve consistency and good quality of documentation.

Conclusion

It is very important for you as a technical writer to know the very basics of the ISO Schematron. Though the technical writers are not responsible for writing Schematron validation XMLs from scratch, having an understanding of the Schematron and the way it behaves is an added bonus in your resume. 

It is also very important for you to understand the difference between the basic completeness/validation check and the ISO Schematron and what are the various constraints that are taken care of in each of the methods.

The use cases which I have provided will help you get clear insights into the ISO Schematron. This article does not contain any technical know-how stuff on writing XPaths for the ISO Schematron. This article, however, gives a clear idea to the writers on obtaining the essential pre-requisite knowledge on ISO Schematron to continue to write great-quality documents.