Technical Documentation: How to Turn Pimcore Into an Editorial System
Instruction manuals in mechanical and systems engineering, software documentation or service manuals in the automotive industry: When it comes to technical documentation, we create a wide range of instructional content for engineering products, some of which are very complex. This kind of content and its generation is usually not in focus when using the data management software Pimcore. However, the software is very flexible and can be customized. This enabled our developers at TANNER to create a lean, cost-effective editorial system that allows people without in-depth system knowledge to develop technical documentation.
Have a glance on this demonstration to get a first impression of the possibilities of the editorial system (only in German).
Why Pimcore is well suited to the specific requirements of technical documentation
Whether assembly instructions or online help – instructive technical contents serve both to provide precise and comprehensible instructions for product users and to protect the manufacturer from liability. The content and form of technical information are therefore highly regulated. Terminology, style, grammar, syntax, and content structure follow well-defined controls aimed at unambiguity, comprehensibility, and translatability. Phrases or filler words are undesirable. Technical documentation content is not as flexible and versatile in its formulation as, for example, marketing-oriented content for e-commerce.
The strong professional structure of technical content fits very well with the structured nature of a PIM system. This and the 100% customizability of Pimcore are used in our lean editorial system. We use Pimcore objects, modules, and relationships to build the content structure of the respective manual and create input templates for the editorial system's users. Instead of defining fields for product characteristics (e.g., name, SEO name, price, etc.) in the input templates, as is the case in data modeling, we use user-defined text fields. Thus, modules for structured product data become modules for texts that can be phrased at random.
Writing an instruction manual using the PIM system
The text below shall illustrate the principle of how to use an instruction manual. The latter must meet precise content requirements. Operating manuals contain standard contents such as prerequisites, personnel qualification, installation instructions, maintenance, troubleshooting, cleaning, warnings, etc.
Our instruction manual is considered an object in the Pimcore editorial system. It contains modules for all contents provided in the manual. The order of the modules determines the structure of this object. The modules contain user-defined text fields for the information to be written. These fields are named in a meaningful manner and provided with instructions for the user of the editorial system.
Intuitive and safe to use
For example, a warning must convey the nature or source of the hazard, the consequences and calls for action. There is a separate user-defined text field for each type of information. This simplifies the compilation of the necessary information and ensures that nothing is omitted. The use of this editorial system is easy to understand and intuitive, comparable to the use of a CMS system such as WordPress. This enables people with little experience in the use of editorial systems to create technical documentation with support of the system.
Efficient utilization of product information
When preparing technical documentation, we adopt the basic principle of the data management system and use many of its functions. A manual created as a Pimcore object is modular, so its individual contents can be reused flexibly. For example, the technical data of a product are required in the product data and the corresponding chapter in the technical documentation. Once created, this content can be played out at all relevant points and kept up-to-date centrally – according to the same principle we know from product data management in the PIM system. Since the content in this system is media-neutral, they can easily be prepared for publishing in different print and online media.
Content management with documentation-relevant functions
Furthermore, we added special functions of Pimcore, which have been extended for technical documentation. One example is the optimized translation administration with status management. Using this feature, the whole document is always submitted for translation. However, only those parts can be edited that are released for this purpose. The status keeps the editors always up to date. “Not translated”, “In translation”, “Translated & outdated” or “Translated & up-to-date” provide information about the most recent status. The release process of documents and the components these documents contain is also easy to understand and it is well organized owing to the status information. One additional feature is the enhanced comparison of document versions. This enables changes between two versions to be made visible immediately in the layout of the document.
All technical information is up-to-date and available for use
Using Pimcore as an editorial system has even more advantages, especially if the software is currently in use for the management of product information. In this case, it is common practice to upload the documents created by the technical editors as assets into the PIM system and link them to the relevant product information. These assets are usually PDF documents, i.e., fully published media. In this format, content is readable at best, but cannot be used for other channels. As a result, although product information is kept up to date, technical documentation changes often incur high logistics or printing costs. This potential conflict does not exist if the production of technical documentation is combined with the product data world in one system.
Promoting digitization in the company
If all product information, including technical documentation, is accessible and easy to retrieve for every department in a company, many processes are optimized. Whether it be the translation of content or its use in marketing, sales, etc. in which case efforts, costs, and processing times are reduced. The quality and usability of the data are enhanced, and the digitization in the company is advanced.
A content management system within Pimcore can be implemented quickly and is cheaper and easier to use than a professional content management system with a broad range of functions. Not only are editorial writing experts, but also every developer, product manager, or service employee can use the editorial system for the compilation of technical content.
Today, product data and technical documentation are required digitally. What could be more natural than to use the flexibility of Pimcore to create this content right here, so that it can be used anywhere in the company and across all sales and service channels?
About TANNER AG
TANNER AG is a leading service provider for technology communication. As a full-service provider, it has been supporting corporations and medium-sized companies in marketing, sales, and after-sales for over 35 years. With relevant content, effective design, digital tools, IT processes, and IT infrastructures for the efficient implementation of digitization strategies. TANNER AG customers come from all B2B sectors.
The company is headquartered in Lindau on Lake Constance. TANNER AG has eight further locations in Germany as well as subsidiaries in Switzerland and Vietnam. With more than 180 specialists, the company develops individual communication solutions using modern procedures and tools.
Want to submit a guest post to Pimcore's Blog?
Submit a guest post and benefit from our network! With our newsletter, we reach more than 5 000 subscribers and attract more than 50 000 monthly visitors to our website, and we're always looking for more brilliant contributors to join our ranks. Contact us.
Do you want to become part of the next generation of Pimcore partners? Please visit our partner application page.