Tech Documentation Management System For Manufacturing
How switching from an outdated DITA-based software to *instinctools’ feature-rich DITAworks helped a Danish enterprise fully digitize tech documentation management, speed up document-related operations by up to 14%, and reduce translation costs by 11%.
Industry:
Manufacturing, Energy
Software Product Development
Enterprise Software Development
Business challenge
Manufacturing organizations must ensure their products are accompanied by technical documentation and then keep an eye on its relevance and updates. At enterprise level, when the number of products and their variations grows to hundreds and even thousands, technical writing and its management become more challenging and the call for a specialized software solution becomes louder.
DITA is one of the well-known standards that can lighten this burden while speeding up the process at a wallet-friendly cost. However, finding ready-made software with suitable functionality among the diverse DITA-powered options out there is almost as unlikely as finding a needle in a haystack. That’s the struggle our client faced.
DITAworks Webtop is a DITA-based multi-processor software product with a solid content reuse mechanism for authoring, managing, and publishing tech documentation. As an enterprise-oriented system with a modular architecture, it’s flexible and highly customizable to meet the needs of companies with mature content structures.
- Limited Content Map development functionality
- Only basic metadata and conditional processing (CP) tags
- Inflexible search options
- Underdeveloped management of reusable content elements
- Inability to work on a single piece of content in isolation without affecting its usage across the whole content system
- No detailed history view
- Absence of translation status analyzer
Driven by all these issues, the client started re-investigating the market for an advanced DITA-based software provider. To make sure their future partner could be on par with the highest quality and security standards, the client narrowed down their options to companies compliant with ISO 9001:2015 and ISO 27001:2022 standards. That’s how *instinctools and our DITAworks Webtop showed up on their radar.
What has our team done to turn DITA into a business asset worth investing in and obtain the full value this standard can bring?
Solution
As security is a top priority for enterprises, we provided the client with a standalone DITAworks Webtop application hosted on their own server in the Digital Ocean to ensure the Fort Knox safety of the company’s sensitive data.
Advanced DITA content
migration from the client’s
former DITA CCMS
The first step our dedicated team took was writing migrators to move the client’s DITA content from their old solution to DITAworks. Simple data migration regardless of the specifics of content organization wasn’t a go-to option, as it requires manual re-sorting afterward.
- Automated post-migrational content reorganization. We wrote migrators powerful enough to automate map formatting, grouping topics of different types into relevant folders, etc., to speed up the process and eliminate the possibility of human error.
- Tailored DITAworks’ content hierarchy to the client’s current content structure. It helped smoothen transition to the new system for the staff.
This approach resulted in hurdle-free content migration between the systems.
Out-of-the-box DITAworks’ features that bolstered tech documentation management right away
As DITAworks grants extensive functionality off the shelf, its adoption helped the client fine-tune their content-related processes right from the start even before tapping into bespoke advantages brought on by custom features.
Glitch-free topic editing
DITAworks uses an up-to-date oXygen™ XML editor whereas the client’s previous system ran on the obsolete and ill-performing oXygen™ Applet, leading to constant lags in topic editing. Switching to DITAworks solved this issue and unlocked flawless access to the editing functionality for authors and reviewers.
oXygen™ is a multi-platform collaborative tool for creating and editing XML files, validating their structure, etc. It supports single-source publishing and allows users to produce XML content in multiple formats (PDF, HTML, Web Help, XHTML, EPUB, etc.).
Rapid publishing speed
Unlike other single-processor DITA-based products, DITAworks supports various DITA processors for content publishing by default, empowering users to control the publishing speed. Our client leveraged two processors:
- DITA Open Toolkit for 90% of their tech documentation, which didn’t require immediate publishing.
- DITA XMLmind for the remaining 10% that had to be published in less than one second.
To set the processor for a particular piece of content, authors just need to choose one from the drop-down menu in the pre-publishing configuration.
Extensive range of reusable elements
Reusability is a linchpin of any DITA-based software, and the diversity of the reusable elements directly impacts the speed of creating, translating, and publishing tech documentation. In the client’s original system, there were only two basic types of reusable components – text block and text template.
After adopting DITAworks Webtop, authors and translators gained access to a plethora of reusable elements:
- Keywords
- Blocks of text
- Text template
- Topics
- Map components
- Context text block
- Context variable
Moreover, we extended the range of actions users can take regarding the reusable entities. Besides adding new components, editing the existing ones, and deleting them, it became possible to redefine the meaning of the current context.
This feature comes in handy when the staff need to work on a specific piece of content without affecting its other use cases across the whole system.
Another detail about our reuse approach that made DITAworks a more user-friendly product than the client’s former system was using indirect links instead of relative ones to provide a path not to an object, but to its key. This way, users don’t have to worry about the links’ integrity when moving objects.
Advanced search functionality and metadata customization
The full power of reusability can’t be achieved without comprehensive search features, and this was another weak point in the client’s old software – it didn’t allow a full-text search.
Conversely, DITAworks offered broad search capabilities out of the box:
- By title
- By full-text
- By phrase
- By CP tag
- By metadata
The last point was a treasure trove for the client as it went beyond the basic topic title and type (concept, task, reference, etc.). DITAworks relies on the taxonomy framework and allows indexing any metadata and using it for search at any system level.
In software product development, taxonomy is a hierarchical classification of the product elements that streamlines data organization in a logical order and, by doing that, levels up search capabilities within the system.
Our client applied this feature for tagging specific product-related topics, as the range of the solutions they produce varies from control devices for decentralized power production to the ones for marine and wind turbines. As the DITAworks’ search engine indexed all the custom meta tags, such an approach simplified finding data on thousands of products.
Unlimited customization of CP tags
Any DITA-based software has in-built conditional processing (CP) tags. However, not every solution makes them easy to use. For example, to operate on the client’s former system, users needed a basic knowledge of XML to create a custom CP tag. Moreover, as the process was manual and authors wrote tags by themselves, the likelihood of human error remained high, affecting the accuracy of tech documentation management.
DITAworks’ adoption helped the client:
- Create custom tags without XML knowledge
- Automate tagging if a CP tag already exists in the system
- Eliminate human-related errors
Custom DITAworks’ features
tailored to the client’s needs
Custom functionality is usually the point of the utmost importance, especially for enterprises. Therefore, DITAworks is designed around the idea of boundless adaptability of the product. The *instinctools team crafts various functionality sets to meet the needs of any enterprise client by connecting or disconnecting numerous plugins to the off-the-box DITAworks version. Let’s see how custom modifications have opened the door to a multitude of tailored benefits for the client’s tech documentation management.
Map development
Creating content maps and managing the content tree are tricky day-to-day tasks enterprises have to deal with. Therefore, extensive map development functionality is one of the vital criteria for companies choosing between different DITA-based products. That was the same for our client, who had a highly sophisticated content tree.
DITAworks Webtop enables multifunctional map creation and editing. Users can access different functions directly from the map editing menu instead of switching to a separate tab.
- Map structure editing. Thanks to the interactive interface, the client’s employees can change the map structure quickly and easily in the left section with the content tree. They just need to drag any element and drop it wherever they want.
- Topic editing is central. Here users can check the content in the preview and proceed to editing.
- Search. On the right side, there is a repository navigator with a search bar to simplify browsing topics and linking them with the maps.
- Conditional processing can be used on the level of the topic, map, or their units. For example, an author can assign a specific CP tag to a map unit and then leverage it for filtering.
Custom versioning
Transparency and the ability to dive deep into every piece of content were the client’s top requirements for the new system, so we honed DITAworks’ versioning functionality to match these needs.
Advanced History View. In their former system, the client could see only the latest version of the documents, which failed to bring much-coveted visibility into the changes made to the files.
In DITAworks Webtop, every document check-in is tracked and leads to creating a new version (revision) of the file. Authors, translators, and administrators can:
- See all the document versions
- Compare the current version with any of the previous ones
- Select any version of the document and restore it
Flexible current working context settings. One of our client’s specific requirements came from their mature content structure with its multi-level hierarchy. In addition, the company organized the work of authors, translators, and administrators in a way that aimed to collect topic-specific content in one place and reduce cross-linking between different levels, and DITAworks had to be tailored to this workflow.
Therefore, specifically for the client, we developed a ‘Dive into’ functionality that allowed users to set any folder as a root in the current working context, making folders outside this folder temporarily inaccessible through the search and repository navigator. This feature freed the staff from the constant hurdle of re-opening folder-in-a-folder-in-a-folder when operating in the same working context for a long period of time.
Ability to work on an isolated piece of content
The next feature that was initially created for our Danish client and then became out-of-the-box was intelligent custom versioning with branch and baseline management. This functionality allowed users to work with an isolated piece of content without affecting the whole content structure.
- Branching for parallel translation tasks. Our client supports tech documentation in multiple languages. The standard ones, aside from English, are French and the CKJ group (Chinese, Korean, Japanese). Working with a wide range of languages within one operating context would have been inconvenient for translators and could have caused unwanted changes in the root content.
With branching, each user could work independently without affecting the root content. They could create a copy of a parent folder with all the documents in the master language with meta tags and after finishing the translation merge it with the initial folder. - Baseline for minor edits. As a lightweight version of a branch, the baseline offers users a copy of the content indexes. It is enough to make slight changes, such as correct misspellings.
Translation analyzer
Tracking translations’ status is just as important as creating tech documentation, and the translation analyzer is the component of DITAworks that covers this task. It’s a table with checkboxes for selecting files for translation. For example, users can pick only one project and leave the rest untranslated.
When a user creates a translation, the system automatically links it with the document in the master language. It’s necessary for tracking content changes and getting translation status updates in near real-time.
Release management
After enriching the out-of-the-box product with a range of custom features, the *instinctools team integrated DITAworks Webtop with the client’s website for direct content publishing. Such a connection allowed the client to provide their customers with the most relevant and accurate documentation.
Conducting staff training
Before rolling out the DITAworks, our team ran training sessions for the client’s employees to ensure they could leverage the software’s capabilities to the fullest. All the sessions were recorded, laying the foundation for the client’s DITAworks knowledge base and nurturing in-house expertise.
The response to the new powerful product has been very positive, and many newly trained tech writers, translators, and managers have become advocates for the system.
Before
- Underdigitized technical documentation creation and management process
- Weak content reuse mechanisms
- Lack of history view and in-depth version control
- Poor search and conditional processing functionality
- Impossibility to work on a piece of content without affecting the whole content ecosystem
- Tight limitations of the working context
- Human errors in CP tags due to manual input
After
- Fully digitized technical documentation creation and management process
- Advanced history view with transparent version control
- Broad search capabilities
- Limitless metadata and CP tags customization
- Ability to work on an isolated piece of content
- Flexible current working context settings
- Automated management of CP tags
Client’s testimonial
Here’s how the company’s CTO evaluates the project outcomes:
Business value
- Complete digitization of authoring, managing, and publishing tech documentation
- Custom product tailored to the company’s specific document management workflow
- Reduced document creation time by up to 14%
- Cut back on translation costs by 11%
- Minimized possibility of a human error
Multiplier effect
The adoption of DITA-based software attracts the companies thanks to well-honed, accelerated, and budget-friendly tech documentation management. However, according to our observations, many organizations still use non-specific software such as MS Word, and business owners tend to see switching to the dedicated tech documentation management system as a major head-scratcher. It’s truly one of the trickiest tasks.
Nevertheless, booming AI technologies play their part – converting Word content into a DITA-ready format no longer needs to be done manually. It can be covered by artificial intelligence. Instinctools is also leading the pack and constantly bolstering DITAworks’ functionality with forefront technologies to simplify and speed up the data migration process while perfecting its accuracy and security.
