Inhaltsverzeichnis
Spellcheck – even Word can do it, with more or less good results. There are also correction programmes for grammar and style. And consistent terminology can be achieved with specialized tools. In technical writing, there is a multitude of authoring tools available to help us edit content. But usually these tools only target the content. Therefore, we have developed our own tool that analyses the content, but also takes a close look at the structure of the publication: our ContentRuleset. In this article, we would like to present how the tool works in practice.
Structural issues
If you work with SCHEMA ST4 as a content management system – and this is the prerequisite for the doctima ContentRuleset – you know what a project looks like shortly before publication: hierarchically nested nodes of different information types, reused graphics, fragments etc. Depending on the amount of information, many things come together. And when you have produced the document and look through it again, you might notice the first issues:
- Wait a minute, why is there no cover image on the title page?
- The list of tables comes before the list of figures. Isn’t it the other way round with the rest of our documents?
- The safety chapter is a subchapter of the introduction. Shouldn’t it be an independent main chapter?
- The imprint is missing, it still has to be integrated.
- It says, “… you will find in Appendix B”, but there is no Appendix B at all.
- … and so on.
Such mistakes happen while creating projects, so even a style guide only helps to a limited extent. It would be convenient, however, if there was a tool that checked the project for exactly such errors.
… and structural answers
User interface of the doctima ContentRulesets
The ContentRuleset is integrated into the Schematron module of ST4, where it does not only access the content but also the structure of projects. What does this mean exactly?
You can check in your project, for example whether:
- a certain chapter sequence is adhered to, e.g. whether the “Notices” chapter always comes before the table of contents, the list of figures always before the list of tables, etc.
- a certain chapter hierarchy is adhered to, e.g. whether a chapter that is supposed to be a main chapter actually is one, or whether it has been moved to another chapter as a subchapter
- defined node types are used, e.g. whether the chapter “Security” was created with the corresponding node type.
- fragments are used correctly, e.g. whether warnings are always implemented as fragments.
- all link targets are present in the current project, or whether there is a deleted link or a link to a target outside the project.
- certain nodes contain obligatory content, e.g. whether there is a node with a certain mapping ID in the production resources or whether there is actually an image linked in the node “title image”.
- there are still comments of a certain type that actually have to be answered and deleted before production
- and more.
The output of the check run also takes place in ST4 and, per mouse click, leads you directly to the node in which a conspicuous spot was found.
The ContentRuleset takes care of everything!
With the structure check, the ContentRuleset offers a control option that you cannot achieve comparably with other means. But not only the structure is checked: style, grammar and typography can also be checked via the ContentRuleset and queried for undesirable aspects, such as
- sentences that are too long or convoluted
- undesirable terms or abbreviations
- undesirable character formats, e.g. “underlined”
- units without spaces
These and similar checks are carried out using rules. 600 of these rules are already defined in the doctima ContentRuleset, taking industry standards into account, such as the tekom guideline “Rule-based writing”.
Further individual rules can be developed and added as required. Each rule can also be classified as a
- critical error
- error
- warning, or
- info
so that you can see immediately whether there are still major errors and where they are located, or whether it is just a matter of “fine tuning”.
This helps you detect errors before production and gain time in quality assurance. A high level of consistency in your documents is thus guaranteed.
If you would like to learn more about how to use the doctima ContentRuleset and, if necessary, customize it to your specific needs, we will be glad to provide additional information. Send an e-mail to benjamin.rauschenberger@doctima.de, and we will be happy to present the tool to you.
