TJ Dhaliwal, Stilo
October 1, 2023

Overcoming Roadblocks on the Journey to a Structured Standard

In today’s rapidly evolving digital landscape, structured content is essential for organizations to manage and deliver their information efficiently. A structured standard systematically organizes and presents content, enabling seamless integration across multiple platforms and channels. However, transitioning to a structured standard can be challenging, and often hindered by various roadblocks. This article will explore some common roadblocks and strategies to overcome them, focusing on getting stakeholders on board, scoping the project, addressing resistance to change, handling legacy content, and managing limited budgets and resources. Additionally, we will briefly touch upon industry applications of a specific standard like DITA.

Getting Stakeholders on Board

One of the initial challenges when implementing a structured standard is gaining the support of stakeholders. Many organizations have well-established processes and workflows that may resist change. To overcome this obstacle, it is crucial to demonstrate the benefits of a structured standard, which include improved content consistency, easier content reuse, enhanced searchability, and increased productivity.

• Engaging stakeholders in open discussions and highlighting how structured content can positively impact their respective roles and overall organizational goals
• Providing examples and case studies of successful implementations in similar industries to instill confidence and garner support.
• Offering training and workshops to help stakeholders comprehend the value and potential of structured standards and address any concerns they may have.

Problems with Lack of Research and Legacy Content

Legacy content, often stored in various formats and systems, can pose significant challenges when transitioning to a structured standard. In many cases, legacy content lacks the structure and metadata required for seamless integration into a structured standard. However, it is essential to address this roadblock to ensure a comprehensive and consistent implementation. Organizations can undertake content audits to identify and categorize legacy content. This process involves reviewing and analyzing content, determining its relevance, and mapping it to the new structured standard. Collaboration with content experts and leveraging specialized tools can help streamline this process and ensure the integrity of the content.

Before embarking on the journey towards a structured standard, assessing the existing content and data is important. However, a lack of data can make scoping the project a challenge. In such cases, starting small and focusing on a pilot project or a specific subset of content is recommended. By doing so, organizations can gather data and insights to inform subsequent implementation phases. This iterative approach allows for course corrections and ensures a more efficient and effective transition to a structured standard. Organizations can refine their scoping and implementation plans as the project progresses and more data becomes available. Stilo’s Analyzer audits large amounts of source content at once to better understand metrics before committing resources. More on this later.

Resistance to Change from Content Creators

Another common roadblock on the journey to a structured standard is resistance to change from content creators. Content creators are often accustomed to their existing workflows and tools, and introducing a new structured standard may seem daunting to them. To address this, it is important to involve content creators early in the process and communicate the benefits of the structured standard. Provide training and support to help them understand the new processes and tools associated with the structured standard. Emphasize how the structured standard can streamline their work, enhance content quality, improve collaboration with other team members, and address their concerns to ensure a smooth transition. Stilo’s Migrate allows users to convert legacy content on an ongoing automated basis, allowing authors and teams to continue writing content in their preferred format and styling.

Limited Budget and Resources for Writers and Teams

Limited budget and resources can present significant obstacles when implementing a structured standard. However, organizations can adopt strategies to overcome these challenges. Firstly, it is crucial to prioritize resources based on the overall objectives and benefits of the structured standard.

An important part of distributing resources appropriately is identifying key problems that require immediate attention and can be costly if not addressed. Consider the long-term return on investment and the potential cost savings and efficiency gains that a structured standard can bring. Additionally, organizations can explore outsourcing options or consider implementing cost-effective solutions, such as leveraging open-source tools and cloud-based platforms. Collaboration with external vendors or industry experts can provide additional support and guidance while optimizing resource allocation.

Benefits of Transitioning to a Structured Standard

Transitioning to a structured standard like DITA offers numerous benefits to organizations in managing and delivering their content effectively. Let’s explore some key advantages of adopting a structured standard:

1. Consistency: Structured content ensures consistency in organizing and presenting information across different documents, platforms, and channels. Organizations can maintain a uniform look and feel by defining a standardized structure, ensuring a cohesive brand experience for their audience.
2. Reusability: A structured standard allows content components to be easily reused across multiple documents. This reusability eliminates the need to recreate or duplicate content, saving time and effort for content creators. It also enhances consistency and reduces the risk of errors from manually copying and pasting information.
3. Flexibility and Customization: Structured content enables organizations to tailor content for different platforms and channels. With a modular approach, content components can be assembled and customized to meet specific requirements. This flexibility allows organizations to deliver targeted, personalized content, enhancing user experience.
4. Searchability: Implementing a structured standard improves search capabilities within content repositories. Metadata and tagging associated with structured content make it easier for users to find the necessary information. Advanced search functionalities can be utilized to filter and locate specific content components, saving time and improving overall productivity.
5. Translation and Localization: For organizations with a global reach, structured content simplifies the translation and localization process. Translations can be managed more efficiently by separating content components from their presentation. Translators can focus on translating individual content components, reducing redundancy, and improving translation consistency.
6. Collaboration and Workflow Efficiency: A structured standard facilitates content creator and stakeholder collaboration. With clear guidelines and defined processes, team members can work together seamlessly. The structured approach streamlines content creation, review, and approval processes, improving workflow efficiency and reducing bottlenecks.
7. Future-readiness: As technologies advance, structured content provides a future-proof foundation for organizations. With a structured standard, organizations can quickly adapt and integrate emerging technologies such as AI, NLP, and chatbots. This adaptability ensures organizations can leverage the latest innovations to enhance their content delivery and user experiences.

Difficult Aspects of Converting to DITA

The conversion process itself can prove challenging depending on your source format. As a conversion provider, we encounter a wide variety of issues that can be mitigated with proper foresight.

One illustrative example involves directing content bodies to specific topic types. Achieving this task can be daunting, particularly when it comes to avoiding specializations. However, this challenge can be easily resolved by introducing a prefix to the containing header, such as “C_” for concepts, “T_” for tasks, and “R_” for references. Subsequently, by employing an automated tool like Stilo’s  Migrate, we can effortlessly route these topics to their respective types without any margin for error or guesswork. With a modest amount of pre-conversion preparation, we can circumvent the need for more labor-intensive post-conversion efforts.

Furthermore,  Migrate can also automatically remove these prefixes while preserving the heading text as intended during the conversion process, eliminating the need for post-cleanup.

Common pitfalls with various source formats

Microsoft Word

One of the most prevalent issues encountered during DOCX conversions is improper styling. In this authoring format, it’s possible to make content appear a certain way without applying consistent styling, leading to confusion during conversion. For instance, instead of applying a Heading 1 style, some may choose to increase the font size of text and assume it looks the same, even though the underlying formatting may differ. This inconsistency becomes apparent when inspecting the XML version of a DOCX document, which can be achieved by saving it as a .ZIP file.

Fortunately, Migrate provides a solution by allowing users to automatically convert incorrectly formatted content based on underlying properties using predefined rules. This feature saves significant quality assurance and review time by simplifying rule adjustments. To learn more about rules and Migrate, visit https://www.stilo.com/migrate-dita/.

In this first screenshot, we can see that the two headings appear to have the same formatting:

 

However, in the xml view, we can see this is not the case:

 

 

Heading1 is applied to “Batch Compiler” but not “About Batch Compiler” which should be Heading3. Likewise, “Installing and Configuring Omnimark on Windows is Heading3”.

This is more clearly seen in the Rules Editor in Migrate:

Here’s the first heading, incorrectly styled in the Rules Editor:

 

Here’s the second, correctly styled, as viewed from the Rules Editor:

Although they look the same, they are not.

 

Adobe InDesign

InDesign is often considered the PowerPoint version of authoring tools, heavily reliant on visual elements. The ability to drag and drop content blocks, even outside the workspace, can lead to conversion challenges. To address misaligned content, utilizing the sidebar in InDesign is advisable to ensure the content hierarchy is correct. A simple drag-and-reorganize action within groupings can prevent the need for post-conversion content adjustments.

Go to Window > Layers to open the following menu, then, just click and drag the content in your desired order.

 

 

 

 

 

 

 

 

 

Adobe FrameMaker

FrameMaker has long been regarded as a powerful tool for technical writing. However, as content evolves and style guides struggle to keep pace, authors may be shoehorning content into styles that do not align with their intended output. This situation resembles the Word formatting issues mentioned earlier but with less freedom to experiment. Nevertheless,  Migrate can effectively address these incorrect stylings easily, employing simple rules to capture them.

 

Another common challenge in FrameMaker involves handling images, especially those composed of callouts and complex paths.  Migrate offers a solution by capturing these images and preserving them as SVGs, ensuring that callouts and paths remain intact during conversion.

 

Decisions to Make Before Converting to a Structured Standard like DITA

There are many decisions to make depending on your intended target and the use of your end case. Publishing your content appropriately depends on whether you want a DITAMAP vs. regular MAP. It also depends on what kind of <metadata> you want to include. Another important strategy is content reuse – keys? Conrefs? Relationship tables? We recommend having an information architect to thoroughly help build your ideal target DITA to suit your needs.

Let’s have a look at some of the differences between the options above.

DITAMAP vs MAP

A “ditamap” and a “regular map” refer to two different types of map files used for organizing and structuring content. These maps are fundamental components of DITA, a markup language designed for creating and managing structured documentation. Here are the key differences between a ditamap and a regular map:

DITAMAP:

Primary Purpose: A ditamap (short for “DITA map”) is the primary map type used in DITA. It serves as a high-level organizational structure for topics, maps, and other resources in a DITA project.

Contents: A ditamap can contain references to various types of DITA resources, including topics, submaps, and references to external files. It provides a hierarchical structure for organizing these resources.

Hierarchy: A ditamap can have multiple levels of hierarchy, allowing you to create a structured outline of your documentation. You can use ditamaps to define the order in which topics should be presented and to group related content together.

Output Generation: When you generate output (e.g., PDF, HTML) from a DITA project, the ditamap serves as a guide for the publication process, helping to determine the order and inclusion of topics in the output.

Regular Map:

The term “regular map” is not commonly used in the DITA terminology. In some cases, it might refer to a submap within a ditamap. A submap is a map that is referenced within another ditamap to provide a modular and reusable structure. Submaps are considered “regular maps” within the context of the parent ditamap. This helps when converting multiple documents or files that are part of one “project” but then will be encapsulated into a larger repository under a DITAMAP.

Purpose: A submap (or what might be referred to as a “regular map”) serves a similar purpose to a ditamap but at a more granular level. It can be used to organize and structure a subset of content within a larger DITA project.

Inclusion: Submaps are typically referenced within a ditamap to include their content in the overall documentation. This allows for content reuse and modularity, making it easier to manage and update specific sections of documentation independently.

In summary, the main difference between a ditamap and a regular map in DITA is that a ditamap is the primary, high-level organizational structure for a DITA project, while a regular map (often referring to a submap) is a lower-level map used for organizing and structuring specific sections of content within a larger project. Both types of maps play essential roles in creating structured, modular documentation in the DITA framework.

METADATA

Metadata in DITA, is a fundamental component that enriches the management and accessibility of structured content. It serves a multifaceted role by providing context and additional information about DITA elements, such as topics, maps, and components. This metadata includes details like authorship, version, keywords, and publication date. Such descriptions are instrumental in efficiently organizing, searching for, and retrieving content.

Moreover, metadata facilitates content reuse and localization efforts. It helps determine the suitability of DITA components for various contexts and assists in adapting content to different languages, regions, or target audiences. Metadata also plays a pivotal role in content governance, offering insights into ownership, rights, and permissions, which is vital for aligning content management with organizational policies.

Furthermore, metadata integration with content management systems and publishing tools streamlines content assembly, formatting, and distribution processes. Customizable metadata attributes can be tailored to an organization’s unique requirements, ensuring that metadata serves the specific needs of content management and enhances overall content discoverability and usability. In essence, metadata in DITA serves as a robust tool for content enhancement, management, and customization in structured documentation projects.

CONTENT REUSE

KEYS

Content reuse is a fundamental concept in DITA that significantly enhances efficiency and consistency in structured documentation. One powerful technique for achieving content reuse in DITA is using keys. Keys are user-defined identifiers that associate content in a topic or map with specific elements or resources in other topics or maps. Here’s how content reuse using keys works:

In DITA, keys act as references, allowing you to link and reuse content fragments across various topics and maps. This approach minimizes redundancy and ensures that updates made to a single source are automatically reflected wherever the key is referenced. For instance, you can define a key for a commonly used term, a product name, or a procedural step. When you need to use that term or element in multiple places throughout your documentation, you simply reference the key, rather than duplicating the content. This not only saves time but also guarantees consistency, as changes made to the key’s definition propagate throughout the entire documentation set. Keys are particularly valuable when dealing with content that recurs frequently or requires consistent terminology across a project, contributing to improved maintenance and overall document quality.

Moreover, keys in DITA are versatile and adaptable to various scenarios. They can be used for conditional processing, allowing you to deliver customized content to specific audiences or output formats based on conditions associated with the key. Additionally, keys can be employed to cross-reference content within a map or between maps, making it easier to create structured relationships between different parts of your documentation. Overall, the use of keys in DITA offers a powerful mechanism for content reuse, consistency, and adaptability, which are essential principles for efficient and effective structured documentation.

CONREFS

Conrefs (short for “content references”) are a powerful feature that facilitates content reuse and ensures consistency across structured documentation. Conrefs allow you to include the content of one topic within another topic or map, making it easier to maintain and update shared information. Here’s how conrefs work and their significance:

Conrefs are essentially references to specific elements or sections of content within DITA topics or maps. Instead of copying and pasting content, you can use conrefs to “point” to the content you want to reuse. When you conref content from one location into another, any changes made to the source content are automatically reflected wherever it’s referenced. This ensures that your documentation remains consistent, as updates and revisions are propagated throughout the entire documentation set. Conrefs are particularly useful for repetitive information, such as product descriptions, legal disclaimers, or standard operating procedures.

Furthermore, conrefs in DITA offer granularity that allows you to reuse not just entire topics but also specific elements within those topics. For example, you can conref a single paragraph, a table, a list, or even a single sentence. This fine-grained control over content reuse makes creating highly modular and adaptable documentation possible. Conrefs also support conditional processing, meaning you can apply conditions to conrefed content, enabling tailored content delivery to different audiences, product versions, or output formats. Overall, conrefs in DITA streamline content management, improve consistency, and reduce maintenance efforts, making them valuable tools for structured documentation projects.

RELATIONSHIP TABLES

Relationship tables serve the purpose of visually illustrating connections between various pieces of content within a documentation set. These tables consist of rows and columns, where each row represents a relationship between two elements, and the columns describe the nature of that relationship, such as “See Also” or “Related Task.” The primary goal of relationship tables is to help users understand the interrelationships among topics or DITA elements, aiding in the navigation of related information. By providing this visual structure, readers can more easily explore content relationships, making locating and comprehending pertinent information simpler.

 

These tables are frequently integrated into DITA maps or topics and are used to cross-reference related content. They are pivotal in guiding users to relevant material, establishing dependencies between topics, and offering supplementary information that enriches the understanding of specific subjects. In essence, relationship tables enhance the overall organization and usability of DITA documentation, facilitating smoother navigation through complex information structures and ensuring a more user-friendly experience for readers.

Conclusion

Organizations can unlock these benefits and gain a competitive edge in the digital landscape by transitioning to a structured standard like DITA. The roadblocks that may arise during the implementation process can be addressed through effective strategies and the right tools, allowing organizations to successfully transition to a structured content management approach.

One of our customers saved significant man-hours using Migrate to convert 200 FrameMaker books (over 20,000 pages) over a six-week period, ensuring product release schedules were met. The graph below represents the hours saved.

In conclusion, structured content is crucial for organizations to manage and deliver information in today’s digital age efficiently. Transitioning to a structured standard like DITA may present roadblocks, but these challenges can be overcome with the right approach. Organizations can successfully implement a structured standard by getting stakeholders on board, scoping the project effectively, addressing resistance to change, handling legacy content, managing limited budgets and resources, and leveraging specialized tools. Adopting structured standards brings numerous benefits, including improved content consistency, easier content reuse, enhanced searchability, and increased collaboration. Organizations embracing structured content management can optimize their resources, streamline their workflows, and deliver exceptional experiences to their audiences.

TJ Dhaliwal – Stilo Corporation – Technical Sales Product Specialist