An appraisal of the latest software development SideKick from Ovidius by Carsten Regehly, at SCHNELL Motoren AG.

1. CommunicatorThe Institute of Scientific and Technical Communicators
Autumn 2014
Where are technical communicators?
Finding the location of your colleagues
Why publishing needs
technical communicators
Breaking into technical
marketing communications
Improving your
verbal skills
Learning how to get
accurate reviews

2. Communicator Autumn 2014
56 Case study
SideKick: every author’s assistant
An appraisal of the latest software development from Ovidius by
Carsten Regehly, at Schnell Motoren AG.
Have you ever worked with XMetaL Author
Essential?
XMetaL Author Essential by JustSystems
is part of my content management system
(CMS). It is the XML/SGML editor that enables
me to create and edit documentation that
is stored in the CMS, TCToolbox (developed
by Ovidius). There are a number of positive
reasons for using the XMetaL Author
Essential:
ƒƒ Configuration is quick
ƒƒ It’s easy to use, even for those with little to
no XML knowledge
ƒƒ The system is robust
ƒƒ JustSystems provides powerful APIs
ƒƒ The price.
Around my documentation system I have
other third-party systems that contain
information that I have to use within my
documentation.
These other systems can include spare-
parts systems, software development
systems, CMSs and of course my XML CMS.
JustSystems provides powerful APIs to
assist in connecting different systems. I
approached Ovidius and asked them how
they would solve the problem.
API Connector or not?
Their answer was that they could build one
or more system connectors (see Figure 1),
but I would have to be aware that there are a
number of potential problems.:
ƒƒ Whenever the API of the third-party system
changes, the connector needs to change.
ƒƒ Furthermore, the third-party system may
not be available at all times due to network
or maintenance issues.
ƒƒ Finally, you may not be allowed to access
third-party systems at all for a number of
reasons.
Ovidius suggested a data-centric interface
instead: an XML interface structure is
designed, which is used to relay the relevant
information from the third-party application
to a companion product that communicates
with XMetaL. Any third-party application
can export the data, either directly into the
XML structure or into any other documented
structure (for example, an Excel spreadsheet
or any other XML structure) which in turn
is transformed into the interface structure.
SideKick is the companion product and was
developed for this purpose. This article is an
introduction to the tool and the principles
behind it.
Linking the Spare-Parts Catalogue
Schnell Motoren AG has been developing
combined heat and power (CHP) units for
efficient and sustainable energy generation
from biomass since 1992. As the production
process modernised we have incorporated
various data systems for efficiencies. For the
sake of this article I have chosen to focus on
the Spare-Parts Catalogue. Within the Spare-
Parts Catalogue there are parts with names
and numbers. The names are sometimes
ambiguous but each spare part has a unique
ID number that enables the engineer or
service technician to differentiate one from
the other. Within our documentation the
technical author references the spare part
with a special XML element. The spare-part
ID is coded as an attribute on that element.
The author uses spare-parts references
especially when describing maintenance
procedures containing instructions on how
to insert, extract or service the part. Before
we had SideKick, I would enter the data
manually. It was necessary to manually
select the attribute tag, search for the spare
part in the catalogue and then enter the 7- or
8-digit number. There was plenty of room
for error with that workflow and I was very
happy to receive an alternative.
SideKick behaves as the middle-man
between XMetaL Author Essential and
my third-party system with no need for a
specially built system connector (see FigureFigure 1. To API or not to API?

3. Communicator Autumn 2014
57
2). I only need a new configuration with
each new machine or product I have to
document. This is easy enough since I get
that information anyway from development
or sales (list of relevant spare parts, list of
GUI strings, and so on. ).
SideKick is a data connector that receives
information in a simple, well-documented
XML format. It enables the author to insert
that information into the document in
XMetaL Author Essential as either a reference
(that is later clickable in an electronic
publication) or as hard data.
Benefits
This approach, using a data-centric interface,
is beneficial as all of my third-party systems
can provide me with an XML export that I
can easily synchronise with the configuration
in SideKick. The referencing process
becomes automated and because SideKick
is so flexible it is possible to design or
conceptualise any number of tabs holding
different types of information that I could
require for my authoring. That includes
templates, variables, small, re-usable text
fragments, and metadata, for example, for
configuring variant information, target
groups, and so on.
The fact that I can add pre-configured
information into XMetaL with a single
click has reduced my processing time
significantly. I can add variable paragraphs,
include XML elements with complex values
and paste templates with the click of a
mouse. SideKick has reduced my workload
considerably. Additionally, I have all of the
information where I need it. For especially
large amounts of data (I sometimes have
more than 20,000 spare parts to consider),
SideKick has a built-in search or filtering
function that helps sort through the
information efficiently (see Figure 3).
Adoption
In the beginning there were a few things to
get used to. The initial installation was a
bit difficult. I had to contact support to get
it sorted out, which was resolved quickly.
When checking a module out of the XML
CMS, I had to ensure that it was within the
context of a manual to receive only the
context-related configurations that I wanted,
or else I was shown all of the information
available in the system, which was confusing
at first.
Since working with the tool, I have raised
some suggestions that the developers at
Ovidius have taken to heart. The first is
that when an invalid position is chosen for
an element, I would like the information
in SideKick to be greyed out so that I have
no option but to find a new position. Right
now, there is only a tiny error message in
the bottom-left corner that I discovered
only after it was pointed out to me, which
can be frustrating. The other suggestion is
that when I want to place a warning within
the document, I am only shown the XML
structure of the element in the SideKick
GUI. I would, however, like to see the whole
warning, or at least have a colour code for
‘danger’, ‘warning’ and ‘caution’ to be certain
I am using the correct one as they are all
quite similar.
In the future I would also like to do my
own configuration for new data types. The
interface XML-structure is documented well
enough that everybody with some basic XML
and XSLT know-how can take almost any
third-party export data structure and feed it
into the SideKick configuration.
Figure 2. Sidekick: a data-centric interface
Figure 3. Spare-Parts list in SideKick

4. Communicator Autumn 2014
58
Final thoughts
All in all I find this little tool to be an
unbelievable relief for the editor. By
choosing a data-centric instead of a
system-centric approach to interfacing
between systems, I have gained several
benefits. SideKick is a really lightweight
connector between several of my third-party
applications and XMetaL. I can configure it
myself if needs be without programming
experience, and I am not worried about
changes in APIs, availability of third-party
systems or restrictions on system access.
Ovidius is one of the largest suppliers of
XMetaL licenses within Europe and is
available for consultation and configuration
of SideKick and XMetaL, regardless of the
CMS you use. C
Case study
Carsten Regehly has worked in the
field of technical documentation since
2001, and is project manager for the
development, supervision and
analysis of data and interfaces for
generating product and spare-parts catalogues (data
and drawings) at Schnell Motoren AG, Germany.
E: c.regehly@schnellmotor.de
W: www.schnellmotor.de
Translated by Rebecca Newton, Social Media Marketing
Coordinator, Ovidius GmbH.
Tw: @EvylAppel
The Ovidius Social Media Channels:
Tw: @OvidiusGmbH
LI: www.linkedin.com/company/ovidius-gmbh
B: http://blog.ovidius.com
Resources
JustSystems (2014) XMetaL
http://xmetal.com (accessed August 2014)
Ovidius (2014) TCToolbox 7
www.ovidius.com/files/pdf/140611-TCT7_A4_
EN-2.pdf (accessed August 2014)