Where paths can lead when Rome is suddenly no longer the destination

 "Every journey begins with the first step." What always reads so beautifully on calendar pages, we put into practice in 2020, together with our customer Interautomation and took a first step towards company-wide knowledge management.

This was not originally intended to be the case: Interautomation initially only planned to update the operating manual for the data management software they developed for railway transport. When we converted the in-house Confluence system into an editing environment for this purpose, we realised that we could achieve much more. Specifically, build a platform that can be used by all internal knowledge owners to:

• Store expert knowledge for a later date or make it accessible to third-parties
• Document ideas in writing and thus make them tangible
• Expand swarm knowledge within the company collaboratively and as effortlessly as possible

Combined with a uniform structure and a well thought-out metadata concept, it's possible for Interautomation's employees and customers to quickly find the knowledge they need about the software quickly.

Our approach during the project, the advantages of good knowledge management, but also the natural limits of a knowledge platform are the topic of today's article. If you're curious about why of all things technical documentation can act as the catalyst for knowledge management in accompany and why this should be exactly the case more often, we would be happy to take you on our tour.

The "hiking buddies": Interautomation and kothes

Interautomation and kothes have been partners since the Summer of 2020.

While we at kothes see ourselves as a full-service provider of technical documentation and smart information solutions, Interautomation is an expert in many aspects of local passenger rail transport. As a system provider and integrator, Interautomation supports its customers with individual solutions on both the software and hardware sides.

What unites us is that we're each providers of precisely-tailored solutions, and we're therefore also prepared to go off the beaten track if we recognise that it makes sense and is advantageous for our customers. This is exactly what happened recently during a collaborative project whose goal was to document the InLineWeb software developed by Interautomation.

InLineWeb is a software solution that's used in transport companies for operations control and monitoring in the control centre. Essential functions are the on-time determination of all journeys, the automatic counting of boarding and alighting passengers with an occupation determination, the real-time passenger information, the energy-optimised traffic control, the communication with the train drivers and the train conductors and the management of all these constantly running data streams for the downstream reporting.

This list already demonstrates: The software's functionalities are extensive, as is the information to be documented – both internally and externally.

The backpack: Outdated software documentation and an underutilised Knowledge Management System

When our contact, Matthias Baumann, Development Manager for the InLineWeb software, contacted us in the Summer of 2020, it was clear that a journey was to be undertaken, but the destination was not quite clear at that time.

Two milestones were topics of discussion at the time:

1. The updating and optimisation of the existing PDF-based Manual by kothes or
2. The purchase of an in-house Content Management System, in which a new manual could be updated regularly in the future.

This second idea of an in-house Content Management System was driven by the desire for more flexibility with respect to the publication format, as well as easier adaptation options for the manual in the event of extensions to or updates of the software. Interautomation occasionally supplies customers who explicitly request a printed manual. At the same time, it was in Interautomation's best interest to provide its customers with up-to-date and easily updated information. At the same time, it was in Interautomation's interests to provide its customers with up-to-date and easily updatable information – not an unusual requirement in the software industry, known for its short development cycles. The buzzword "Online Help" came up time and again in this context.

For 2020 anyway, there were travel restrictions at Interautomation as well, however: Matthias Baumann was on a solo mission at the time. Initially, it was planned that he alone would develop InLineWeb, publish the required content and expand it as needed. This naturally limited the time and staffing resources available for the creation of the manual. In addition, we quickly agreed that the cost of acquiring and familiarising ourselves with a Content Management System for this specific situation would not be in-line with the benefits we had all hoped we could achieve. The possible destination of "CMS" was therefore crossed off the list again.

Instead, we got to chatting and learned almost by chance that Interautomation had introduced Confluence as a Knowledge Management Platform not that long ago, but hadn't yet fully taken advantage of its possibilities and actual use.

From that point on, it didn't take long for the "route to be remapped" and the individual stages to be defined. The new goal: to create a working environment in Confluence in which Interautomation could create information as quickly as possible and at the same time systematically and in a structured manner, modify and expand it independently; in order to be able to output it later – either as a printable PDF or as Online Help to their customers.

The Hiking Route, Stage 01: Concept Design Workshop

Highlights along the Stage: broad target audiences, Confluence's standard functionalities vs. add-ons & good technical editorial practice

Hiking Guide Rating: Stage 01 falls into the "Challenging" category. Although it's designed as a one-day stage, quite a few (cognitive) meters of altitude have to be covered. The route is therefore suitable above all for ambitious hikers. The varied route and the sweeping views along the way reward the effort, however.

The first part of the route initially took kothes to Berlin for a Concept Design Workshop at the premises of Interautomation. From there, we continued along together.

The day's agenda included four important sightseeing spots:

• Finding out who the external and internal target audience(s) of the knowledge platform are. What do users expect from the content? What specific knowledge do they need?
• Determining what Interautomation's requirements are for the new working environment: How do they want to work? How should workflows and results look? What’s needed for all of this?
• Analysing which user requirements (on both the content creator and content consumer side) Confluence can meet with its standard functionalities. Where will additional add-ons or macros be needed? What's the relationship between effort and benefit? Where will we reach our limits?
• Collecting all the information that's to be included in the documentation. How can it be structured? How can templates simplify creation, at the same time systematising and standardising content? What do templates have to look like in order to meet specific usability requirements?

A well-balanced mix of methods (from persona to user stories to clustering) helped to get all to-dos done at the end of the day, and at the same time, to make a large number of necessary decisions.

Probably the most exciting decisions concerned the technical implementation for publishing the content: We worked out a total of five different publication scenarios for digital publication, investigating and evaluating the advantages and disadvantages of each.

The discussion was based on the following factors: data security, synchronisation and effort for updates, costs for add-ons, costs for licenses, connection options to an existing ticketing system, implementation options for the corporate design (i.e. CI) and the offline availability of the system.

In the end, the decision was made to invest in two add-ons from the company k15t GmbH to meaningfully supplement the basic functionalities of Confluence: Scroll-PDF, to enable an aesthetically pleasing and user-friendly PDF export from Confluence, and Scroll-HTML, to additionally be able to output HTML packages that are integrated directly into the InLineWeb software as Online Help.

The Hiking Route, Stage 02: Implementation Stage

Highlights along the Stage: Implementation of the add-ons, templates & user-friendly navigation structures

Hiking Guide Rating: The route requires a good basic level of "fitness". You'll have to make detours along the way because individual sections of the route aren't passable as expected. Therefore, plan enough stopover breaks and discuss regularly with your companions which alternative routes you'll maybe want to take. 

On the second leg of our route, Interautomation first eliminated roadblocks on the IT side: A separate area for documentation was created in Confluence, the Scroll-PDF and Scroll-HTML add-ons were implemented, and kothes was given access to the knowledge platform. The latter was particularly necessary, in order to be able to design templates directly in the target system, which should simplify and standardise the subsequent creation of content. In the previous workshop, we'd already identified together, a need for templates for the following types of information: dialog description, process description, step-by-step instructions, interface description, troubleshooting, and internal documentation.

During several iteration loops, we worked out templates that were then tested and evaluated by Interautomation and, if necessary, revised by kothes. In addition, we created sample content and, based on our experience in good technical editorial practice, supplemented the templates with so-called "Dtage Directions" to enable Interautomation to work with the templates later, and to create a basis for collaborative documentation creation.

In parallel, we developed ideas for Interautomation to build a comprehensible navigation structure in the Confluence sidebar, to design a visually appealing Glossary, and to create a user-friendly design for the Homepage. Processes for work control, quality assurance and editorial approval have also already been considered.

The Hiking Route, Stage 03: "How to" Phase

Highlights along the Stage: Accessibility of information, technical editorial processes & quality assurance

Hiking Guide Rating: You're now hiking on the home stretch. Most of the route is already behind you and you're cruising along the last few meters. So don't be afraid to pick up the pace again. Because there are also a few things along the way that are worth taking a closer look at. And don't forget to document your journey for posterity and take plenty of souvenir photos!

On the last leg of our project route, we put the finishing touches on the working environment. Interautomation's desire was to make access and use of the knowledge platform as easily approachable and accessible as possible and to make it easier to find the information we needed. For this reason, in this final section we focused once again on keywording the content, optimising the search function, and increasing usability through a use case-oriented Start page and practical FAQ pages.

At the same time, we made great effort to professionalise the technical editorial creation processes in the background: How do we establish version security? Which workflows are needed for the maintenance of the templates? What can sensible release processes look like? Who has which roles and rights during the creation process? How can we ensure uniform terminology? How can we check quality with respect to technical accuracy and linguistic correctness? What rules are required for a uniform visualisation of the software interface?

Our considerations naturally flowed into a kind of editorial guide – also into Confluence, of course.

Excursion to the vantage point of knowledge management – is it worth the effort?

At this point, some of you may be thinking: So what's the point of knowledge management now? So far, this has been classic case of documentation creation, only in a knowledge management tool?

First of all, we should take a closer look at the term "knowledge management" and its meaning: Knowledge management generally encompasses all measures (both operational and strategic) that contribute toward identifying, collecting, structuring and preserving explicit or tacit knowledge for a later point in time, or making it accessible to third-parties.

I like to compare good knowledge management with a well-stocked pantry: Every cook (i.e. knowledge owner) stocks the pantry with the supplies (i.e. their expert knowledge) that are most important to them – regardless of whether they're still in raw form or have already been pre-cooked into re-heatable dishes (remember microwave dinners?). A common system of organisation and good labelling of the storage containers (with metadata) helps to ensure that everyone can take those exact ingredients from the pantry at any time that they need for their dish on that day's menu (i.e. upcoming tasks). In this way, important knowledge stocks are systematically stored for a later point. Or the knowledge is processed by others directly into "delicious new dishes".

The motivation behind this can range from the idea of distributing expert knowledge that's limited to individual experts, to a general increase in knowledge across all employees in a company, to a pragmatic desire to stop wasting time searching for detailed knowledge.

Matthias Baumann nicely summarised the relevance of internal and external knowledge management at Interautomation this way: "It feels like knowledge management is highly-relevant in our company. Particularly internally, because important things are often not known or have to be laboriously compiled all over again. [...] With regard to the resources available in practice, knowledge management unfortunately still has low significance. The hope is that this will change with the first positive experiences we're having with the resulting docu-solution.”  

So is Interautomation now practicing knowledge management with documentation creation in Confluence?

• At Interautomation, according to Matthias Baumann, the Confluence solution has meant that documentation creation is no longer a "lone wolf project [but] a “collaboration project” on which several colleagues [from the project service/support area, among others; Editor's Note] can work and also have fun with this work."

• All Interautomation employees have both editing and creation rights in Confluence and can thus contribute to the permanent growth of the knowledge platform. At the same time, Confluence (and especially the area for documentation) was linked to Jira the ticketing system. Thus, internal as well as external ticket requests and the associated answers to individual key functions are now displayed directly on the corresponding information page. This establishes the development history of key functions, but also any remaining ambiguities for the target audience. The internal knowledge stock is increased. External knowledge can be improved by optimising external content.

For those who are searching, can situationally-required knowledge be found quickly?

• Through the differentiated control of information for external and internal use, only that information is automatically published which is relevant for the appropriate target audience. Through keywording and the consistent use of uniform terminology, information cannot only be searched for, but it can also be found quickly. The exciting thing about Interautomation is that the traditional documentation content can also be made accessible to completely new target audiences, such as the company's own Sales team. Matthias Baumann chimes-in on this: "Before, it was documentation that was difficult to use and was hardly transformable (e.g. Word document), and now it's documentation that can be used flexibly with web access, search functions, and even printability."

So, to us, the answer to the question above can clearly be "Yes": The new way of creating documentation is a form of knowledge management. The fact that technical documentation in particular can be an initial spark for the topic is not at all surprising when you take a closer look. What other industry has so much experience in documenting complicated expert knowledge, making it comprehensible to third-parties, and making it accessible via a good metadata concept and coherent classification?  

Of streams and stumbling blocks

Of course, every system solution reaches its limits at some point, and there were one or two stumbling blocks on our shared "hiking route" as well. For example, it's not always easy to find a compromise between providing users with as barrier-free access to information as possible and protecting your own, sometimes very sensitive, data. We also had to jump over both small and large "flowing streams" over and over when it came to creating content in Confluence in such a way that it looked good – both in portrait PDF output and in Online Help (for screens in landscape format). And, of course, we should mention at this point that Confluence is certainly not suitable for all documentation needs and its suitability strongly depends on the level of complexity.

For the documentation of the InLineWeb software, however, the solution has proven to be quite practicable, which Matthias Baumann can also confirm with his positive feedback: "A working environment has been created with which we can continue to work independently. During the project, the open-ended interaction with kothes was very important: that our own ideas were understood and that kothes distilled solution proposals from them, which we could then evaluate and modify. This is how our initially vague ideas turned into good solutions. Actually, everything was pretty much as we wanted, even in hindsight."

By its very nature, building a knowledge management platform is never truly finished. Knowledge grows constantly, and thus a knowledge management platform must also keep expanding. For Interautomation, this won't only mean that additional functionalities of their software (InLineWeb) will be newly or additionally described. The editorial guidelines will also have to be expanded bit-by-bit, and perhaps even revised periodically. And last but not least, the requirements for a system can of course change as well. It's already becoming apparent, for example, that better translation control or additional version management may be required in the future. There are suitable solutions for this as well – from process optimisation to additional add-ons.

But as the hiking enthusiasts among you surely know: "After one tour is just before the next tour". We'll continue hiking, but for now it's time to arrive and enjoy the glorious view.