On a journey towards productised documentation
In a previous blog post, Tiia Järvenpää wrote about software productisation and how it can be used in a way that enables customer-specific modules and customisation. When moving towards such a productised solution, it is a good time to improve the ways of managing documentation to support it.
Now that we are introducing a modular and customisable product, we need documentation to support it, the most important document being a functional specification that describes its features. In a productised system, the basic features – and thus also the functional specification chapters describing these – are the same in most customer projects. Some features are included in optional product modules, and some features are specific to an individual project.
From Word files to a documentation system
When using conventional linear documentation such as Word documents, it is easy enough to copy-paste the common features to new projects, but making changes in a large number of separate documents is highly error-prone. For this reason, we started looking into a modular documentation system that would enable reuse and, at the same time, customisation.
To be able to support productisation and improve the consistency and quality of our documentation, we looked for the following features in the documentation system:
- Modularity: Each chapter is a separate file, “topic”, which you can reuse in several documents. Write once, use many times – and keep it up to date in a single place.
- Structured content: Content is organised in elements such as “paragraph” and “title”. In the final document, each element appears according to what we have defined in a Teleste-specific stylesheet. This means that the layout and formatting are always the same.
- Versioning: It’s easy to keep track of the changes in documents because the topics and documents support versioning and comparing versions. It is possible to maintain many versions, not only to revert to earlier versions.
- Tags: We can use tags to filter out specific topics or even individual sentences. This allows us to tailor our documents for different customers and projects, but still use the same source content for everyone.
- Variables: We can use variables in the content – for example, a “project” variable is replaced by the project name in the final document.
Preparing for writing in a centralised system
Creating documentation in a modular and structured environment requires a new mindset and some training, which is why we have a dedicated team for this purpose. We have identified the document types that benefit from the new approach and started creating and maintaining the first documents in the system.
To be able to write about a product, we also need to determine the terms that we use to talk about it. Thus, as part of the productisation work, we also started a development project for harmonising the terminology in our documentation. We gathered a list of terms that we commonly use in our documentation, including general railway terminology and also terms that we use to refer to Teleste-specific subsystems and products, and decided on the best terms to use as well as definitions for each term. Specifying the meaning of the terms is just as important as the terms themselves to make sure that everyone is talking about the same thing.
Top 5 benefits for us and our customers
- Document accuracy: Our documents are accurate and up to date, because changes can be implemented and errors fixed centrally.
- Quicker document delivery: Since most of the content in the document is ready and no copy-pasting from other documents is required, our customers can get the documents they need more quickly.
- Consistent terminology and writing style: It is easier to maintain a consistent terminology and writing style in a centralised system. When we write about similar things in a similar manner and always use the same term for a concept, we can avoid misunderstandings and confusion that can cost time and money.
- Improved translation quality: The consistent terminology and style make sure that also the translations are consistent. When the high-quality translations allow the end users to find the information they need in the documentation, they do not need to look for other assistance.
- Consistent layout and formatting: The Teleste stylesheet makes sure that every document published from the system looks exactly the same, making it easy for the readers to recognise the same types of information.
Next steps
Currently, in addition to the functional specification, we are publishing our maintenance manuals and specific user manuals using the new modular system. We will continue to review our documentation to recognise document types that would benefit from a modular approach.
The terminology work will also continue, and it will be easier to introduce new terms now that the groundwork is done and the basic terms have been defined. The new terminology has not yet reached all our documents, as the implementation of the new terms in the vast amounts of documentation that we deliver in our customer projects is not a small task.
Tiina Kaarela
Tiina Kaarela
As Technical Writer at Teleste’s Rolling Stock Manufacturers business unit, I strive to improve our documentation by developing our tools and processes. My goal is that our customers receive documentation that fulfils the relevant requirements and is accurate, consistent, and easily readable.
See my LinkedIn for more information.
