The technology industry has long been a driver of change and in recent years, the way we deliver solutions to our customers has changed dramatically from the traditional waterfall methodologies to agile delivery.
The last two decades have seen a major shift in the way technical communicators create, manage, and publish content. In the past, most documentation was created using word processing softwares, such as Microsoft Word. Nowadays, technical writers are increasingly using structured content creation tools, such as XML editors associated with a CCMS like the one offered by Componize Software.
The combination of this shift in thinking and the increased adoption of DITA by major software vendors means that there is a growing use migration to structured content by organizations with technical writers who understand structured writing and its benefits.
What is structured content?
Is a more efficient and effective way to create, manage, and publish content. It allows writers to reuse content, automate publishing processes, and collaborate more effectively with other writers and subject matter experts (SMEs). It is the result of bringing together two distinct approaches to technical documentation:
- Single-sourcing: which allows authors to create a single document that can be used for multiple output formats and platforms,
- the implementation of dedicated frameworks: such as DITA XML, to enable content reuse.
Together these two approaches have made structured content a far more powerful tool than its predecessors.
In structured technical writing, each topic, paragraph, sentence, list item, or table entry has a function that is strictly defined.
The content is organized in a specific manner. It consists of elements that are arranged in a hierarchy and that can be reused in different ways. Being the opposite of unstructured content, which is not organized in any specific way. Unstructured content is typically found in documents such as word processing documents, PDFs, and PowerPoint presentations.
It is also different from semi-structured content, which is only partially organized. This type of content can be found in word processing documents that have been styled with headings and subheadings.
Structured writing was created to overcome issues that arise frequently when documenting complex systems and products. It provides a structure and framework, in order to:
- enable users to quickly familiarize themselves with the presentation of information in manuals from the same organization;
- provide a transparent and concise user experience;
- ensure accurate and complete documentation ;
- and much more.
What are the challenges when it comes to implementing Structured Content Authoring ?
Learning curve
Learning new processes, tools, methodology etc. was great and easy when initially training to become a technical writer. As time goes by, most people get set in their ways and learning new markup languages, methodologies like minimalism, and DITA start to get daunting.
Costs
There are a certain number of costs that will be incurre. The main areas where you will have to invest in are:
Tools
- CCMS: either an on-premises solution or as a SaaS solution, the cost will generally be per user.
- XML Editor: same as for the CCMS, the costs are usually linked to the number of users.
Training
Training your technical writing team in the different writing architectures; DITA, Markdown, Docbook, all represent a cost. Those costs will be both in paying for the training and in down time for the team. Usually companies will have to suspend or reduce production during the training period.
Migration
Moving from one markup language to another will incur conversion costs. The stricter the discipline in the documents that are to be converted, the faster and cheaper it will be to write a conversion matrix, even if you are using a company that provides data conversion.
You must also add the time to convert, then clean up the conversion, and then to verify the conversion and validate the content, especially if you are in regulated industries, the time and effort might turn out longer/greater than you initially planned.
To cut short this time and effort, make sure you include your quality and regulatory teams in the choice of tools and in validating the conversion process.
Translation
Yes one of the big selling points of structured content and reuse is the reduction in cost of translations. However, a note of warning, the savings will only come into play after having retranslated the converted material, from version n+1. Why?
No matter how good your translation provider and the Translation Memories (™) that you have cultivated over the years, TMs work by identifying segments of information. A segment can be a word, a phrase, a sentence or even a paragraph.
Structured content and the conversion to XML changes the segments by adding elements/tags. A simple sentence previously considered a single segment has now become at a minimum 5 segments:
“The quick brown fox jumps over the lazy dog”
<p>The quick1 <b>brown</b>2 <i>fox</>3 jumps over the lazy4 <u> dog</u>5</p>
Alternatives to structured authoring
While there are many alternatives to structured writing, they are suitable as alternatives dependent on the destination of the content:
- Confluence or wiki-type platforms: platforms that assist teams in rapidly collaborating and sharing knowledge. Use Confluence to document project requirements, assign tasks to users, and provide a collaborative type.
- Desktop publishing (DTP): Adobe FrameMaker (when used in the unstructured format), InDesign, and other tools that allow a free flow of content creation, with improved publication parameters when compared to a simple Word document.
- MS Word, Google Docs and any other word processing software: While they are easy to use and relatively cheap, if not free, the added issues of copy/paste errors, page formatting and length of publication have shown the limitations.
Advantages of Structured Content
Reusable content
The main advantage of structured content is that it can be reused in different ways. For example, a piece of structured content can be used to produce multiple formats (such as HTML, PDF, and EPUB). The multiple format also provides possibilities to deliver content to multiple device types, including paper, online but also to tablets, and smartphones.
As the structured content is broken down into fully independent snippets of information that can be understood outside of its context, this means that rather than copy/pasting the same information to multiple documents, you simply make a reference to the content to be included.
This approach means that when a change is needed for that piece of content, the writer need only change it once, and republish to all the different outputs with one additional click for the updates to be applied to all concerned publications.
Single source approach
This approach also provides savings when it comes to managing translations to multiple languages. Reused content that has already been translated, need not be retranslated when the same content is used in a different publication.
Publishing
Finally, structured content is easier to publish than unstructured content. CCMS, and information architecture standards like DITA mean that the look and feel of the publication is handled centrally, and is uniform across all publications. The author no longer needs to bother with publication parameters such as page widths/margins, table formats, image alignments and so on.
What is DITA XML?
DITA XML, or Darwin Information Typing Architecture XML, is a structured XML framework designed specifically for managing and publishing complex technical documentation.
It enables authors to create modular, reusable content units called topics, which can be efficiently maintained and repurposed across various document types and outputs. The architecture supports fine-grained content reuse through mechanisms like content references, enhancing consistency and reducing duplication in documentation efforts.
DITA is particularly favored in industries where precise and up-to-date information is critical, such as software development, engineering, and manufacturing.
Frequently Asked Questions:
Alternative authoring platforms, such as Confluence or desktop publishing tools like Adobe FrameMaker, offer distinct features and capabilities compared to structured content authoring systems like DITA XML editors.
While Confluence and wiki-type platforms excel in facilitating rapid collaboration and knowledge sharing within teams, they may lack the structured approach and publishing automation features inherent in dedicated structured authoring tools. Similarly, desktop publishing software like Adobe FrameMaker provides advanced layout and formatting options but may not offer the same level of content reuse and publishing automation as structured authoring systems.
Furthermore, traditional word processing software like MS Word or Google Docs, while convenient for basic document creation, often struggle with managing complex documentation projects and maintaining consistency across multiple outputs. Thus, the choice of authoring platform depends on the specific requirements of the project, balancing factors such as collaboration needs, content complexity, and publishing efficiency.
Successful implementations of structured content authoring can be observed in various industries, demonstrating its effectiveness in improving content management and streamlining publishing processes. For instance, in the software development sector, companies have reported significant reductions in documentation time and costs by adopting structured authoring methodologies like DITA.
By leveraging reusable content components and automated publishing workflows, organizations have achieved faster time-to-market for product documentation while maintaining consistency and accuracy across multiple output formats and languages. Case studies showcasing these benefits can provide valuable insights into the practical applications and outcomes of structured content authoring in real-world scenarios.
Structured content authoring significantly enhances workflow and collaboration among technical writers and subject matter experts by providing a standardized framework for content creation, management, and publishing. Unlike traditional methods relying on word processing software, structured authoring tools like DITA XML editors facilitate content reuse, automate publishing processes, and promote effective collaboration.
This shift allows writers to create modular content components that can be easily shared, reused, and updated across multiple documents, leading to greater efficiency and consistency in documentation projects. Additionally, structured authoring encourages collaboration by providing a centralized platform where writers and SMEs can work together, ensuring that content remains accurate, up-to-date, and easily accessible throughout its lifecycle.
