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
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.
What has our team done to turn DITA into a business asset worth investing in and obtain the full value this standard can bring?
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.
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.
This approach resulted in hurdle-free content migration between the systems.
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.
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.).
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:
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.
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:
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.
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:
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.
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:
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.
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.
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:
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.
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.
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.
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.
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.
Here’s how the company’s CTO evaluates the project outcomes:
Creating high-quality tech documentation was a matter of reputation for our company. Therefore, we were very particular about our requirements for the new system’s functionality. The bar was really high, yet *instinctools managed to reach it and even exceeded our expectations. Along with getting the custom system fully adjusted to our needs, we gained a reliable tech partner who values transparent communication just as much as we do.
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.
