Some writers and specialists claim it’s too difficult to write in DITA and that the learning curve is too steep. Some other specialists and documentation managers claim that they can start new hires writing in DITA in a couple of hours. This article is the final part of a series of posts about writing practices that authors must adapt, adopt, or shed.

Letting go of styles

It may seem counter-intuitive, but letting go of specifics from old tools and other proprietary formats is sometimes the most challenging part for authors. When adopting DITA, teams must learn to work with modular and structured content. The latter means that the technical writers are focusing on the content and not on how it looks.

Making sure this list bullet point is just right, the indentation is perfect, changing the title font can eat up 50%, even 80% of the time of content developers. With structured content, a lot of time can be saved by separating the content from the layout and applying automated branding on the different media rather on the content.

The benefits are two-fold:

Letting go of styles also means that the next time your organization logo changes or when the branding is updated, content teams will only need to update the stylesheets once – not all the relevant documents.

Adapting the authoring experience

We discussed using tags instead of styles in the first article in this series. However, it is worth highlighting that most modern structured editors can provide authoring assistance that will help authors transitioning to DITA.

First, most editor tools provide a preview of the content in their interface, thus providing a good visual indication of where tags are missing and how the content will look like, for example, on the web output.

Second, in the editor, the mandatory and sometimes optional expected information is displayed to the writers who then fill in the missing text. As an example, the editor can show you a grayed-out title field in which the author types in the title. Another example is the editor completing the excepted information for a hazard statement.

Finally, authors can adopt forms, where the expected information is provided in drop-down lists and tailored to the information model required by the organization.

Letting go of old tools

Others will embrace the new guidelines, editing tools, and systems without a look behind, however, changing tools and format can be difficult, especially for those who consider themselves experts with their current tools or systems.

Real change management and empowerment are crucial for those who feel they have most to lose with the change.

Ownership does not equal authoring

CIDM has made several great surveys and presentations about the sense of ownership and responsibility developed by content authors. When the content is modular and different people write content, then the authors should:

With modular content, the final document is a combination of topics that are written by different team members. Responsibilities can be split between the different parts and the entire information object, where the document owner is not necessarily the document author.

Organizing with a sustainable framework

The best way to organize work and content with multiple authors is, therefore, to organize a framework for writers. Obvious and typical examples include:

Depending on your tools, these can be enforced with rules and formal reviews. Each of these points, of course, should be understood and agreed upon within the team.

Just starting with DITA? Keep an eye on these symptoms

Although structured authoring makes it difficult, it is still possible to write bad content with DITA. Adopting the standard will not make a difference if you do not keep an eye on things. Peer reviews are efficient, but the following list provides several symptoms that mean things are going wrong:

Further guidance

Help is available on-line and freely from the OASIS committee publications and in the specifications themselves. You can also:

This post ends the series of articles, based on the presentation “DITA Surprise! Unpacking Authoring Practices” delivered at the DITA Europe 2019 conference.



Read part one and part two of this blog series.



This blog was originally published in CIDM’s newsletter CIDM Matters.

Blog AUTHOR

Nolwenn Kerzreho
Technical Account Manager at IXIASOFT

Nolwenn Kerzreho is the Technical Account Manager for Europe for IXIASOFT and has over a decade years of experience in the technical communication industry. She holds a Master’s degree in Technical Communication, Translation, Terminology and Project Management.
An international speaker at leading events and academic colloquiums, Nolwenn teaches at the European Master in Translation at Université Rennes 2, where she introduced DITA in 2009. Based in France, Nolwenn has international work experience in the chemical, Telecom, language, and high-tech industries.

You can connect with Nolwenn on Twitter @nolwennIXIASOFT


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

Some writers and specialists claim it’s too difficult to write in DITA and that the learning curve is too steep. Some other specialists and documentation managers claim that they can start new hires writing in DITA in a couple of hours.

This article is the follow-up of a series of articles about writing practices that authors must adapt, adopt, or shed.

We will focus here on the new practices that authors must adopt when writing using DITA. Of course, the trajectory and requirements for each company are different. Still, the most important hurdles for authors usually relate to these three aspects:

  • Accessibility
  • Navigation alternatives
  • Writing for reuse.

Writing for new audiences and delivery channels

Most writers need to adopt new practices as they must let go of the idea that they own the delivery format and can know in advance what final media will be used for the information they craft. In most cases, difficulties arise from delivering to web channels, including websites, mobile sites, phone applications, or even onboard media centers.

Accessibility – an opportunity for all

New media outputs create new demands on the content crafted but also new opportunities. Accessibility is a major factor that can enhance the content experience for all users, and not only those with disabilities. Accessibility on web and digital formats are of the utmost importance. It may be even mandatory if you are working in a field for broader audiences and public services.

The main guidelines for the Web Accessibility Initiative (WAI) are led and hosted by Web Content Accessibility Guidelines Working Group from the W3 consortium. The impact on content for DITA authors lies mostly in tagging so that the publishing tool can understand and process your content effectively. As a result, screen readers (and other assistive technology tools) can parse the information in an effective way.

Note that the 2.1 version of the guidelines includes new advice for assistant tools and inputs for user experience with motions, rotations, and so on.

Accessibility for images, figures, and tables

Images

The baseline is to use descriptions of images to convey the meaning of these images, graphs, etc. As a rule of thumb, if there is nothing to say about an illustration, it is a good indication that the image itself may be removed safely from the content. Images that are void of meaning are not only redundant; they burden the reader. In the end, they will not even be looked at by users.

The figure element should encapsulate:

Alternative text is the explanatory text for screen-readers. Visually impaired customers will hear a description of the image. Again, if there is no description needed for an image, maybe the image can go away.

Lists

Writers should use the proper lists tags and not commas to list items.

Tables

For table elements accessibility, writers should:

These are the main points each author should adopt for writing DITA content. I strongly recommend every writer to check out the WAI guidelines that are available online for free. You will find that the transformation process complies with the basic rules for web accessibility, including heading levels and tagging, link tagging, and so on, but still provides good insights and reminders.

Alternative navigations

Considering that a narrative path does not apply to most technical information sets, authors adopting DITA can add alternative navigation in addition to a table of content and indexing. The goal is to link related information so that readers can click on links to navigate directly to other parts of the information set. For example, to add a link between a maintenance task and a schedule, or to add a logical sequence for a set of tasks.

But where to place these links? Adding links inside the topic’s body can lead your readers to step outside of the current topic before they finished using it. This poses a threat as they may not come back to complete a procedure or read the entire conceptual information. We already know that best practices on the web recommend adding additional links at the end of topics. DITA offers a better way to automatically create the links at a higher level (in the map), thus removing them entirely from the topics themselves.

Removing these dependencies between topics will remove the need to final check what topics are nested in a document.

Authors should never assume the reading order, and this is also true with topic-based authoring. Avoid adding phrases relating to external information such as heretoforehereafteras you’ll see in the next topic, etc.

Reusing content

One of the main reasons to adopt modular content is the ability for authors to reuse instead of rewrite or copy and paste content.

The best practices2 to adopt are to identify and separate the content for publishing and the content for reuse. Then to reuse wisely. The old joke is that the maximum reuse level is one letter. Still, these reuse methods are listed from the easiest to the hardest:

The standard allows you to select different ways of reusing content. You can use various mechanism, such as:

Keys are becoming more and more widely used; however, the combination of key and conref is possible and powerful.

Additional advice

The final advice and practice for authors would be to a) test and b) document the architecture choices that are made within the organization. An Information Architect would usually help craft the content model, or information design, for your team. If you do not have an internal resource, it is essential that you hire someone with the appropriate level of understanding and experience to help your team.

The validated choices should then be added to your current style guide. You may also want to create templates to help authors. There are editing tools available to integrate your style guide rules directly in your editor.

Note that Comtech Services has contributed a sample style guide that can serve as a starting point for your own style guide3.



Read part one and part three of this blog series.



This blog was originally published in CIDM’s newsletter CIDM Matters.

Sources

1 Web Content Accessibility Guidelines and checklists are available at https://www.w3.org/TR/WCAG20/#content-structure-separation

2 DITA Worst Practices, presentation by Keith Schengili-Roberts https://www.slideshare.net/JackMolisani1/keith-schengiliroberts-dita-worst-practices

3 Comtech style guide template available at https://github.com/oxygenxml/dim/tree/master/info-model

Blog AUTHOR

Nolwenn Kerzreho
Technical Account Manager at IXIASOFT

Nolwenn Kerzreho is the Technical Account Manager for Europe for IXIASOFT and has over a decade years of experience in the technical communication industry. She holds a Master’s degree in Technical Communication, Translation, Terminology and Project Management.
An international speaker at leading events and academic colloquiums, Nolwenn teaches at the European Master in Translation at Université Rennes 2, where she introduced DITA in 2009. Based in France, Nolwenn has international work experience in the chemical, Telecom, language, and high-tech industries.

You can connect with Nolwenn on Twitter @nolwennIXIASOFT


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

Some writers and specialists claim it’s too difficult to write in DITA and that the learning curve is too steep. Some other specialists and documentation managers claim that they can start new hires writing in DITA in a couple of hours. This article is the first part of a series of posts about writing practices that authors must adapt, adopt, or shed.

There is a lot of confusion about how difficult writing in DITA can be and this article’s goal is to clarify the challenges for information developers and technical writers alike. This article is based on my experience teaching DITA authoring to two main audiences:

Of course, the learning path depends on each individual’s experience, grasps of concepts, and know-how. However, three main aspects emerge that everyone can relate too, depending on their experience.

Teachers and trainers can use those as a basis for assessing the learning requirements for each group. This article will talk about the first of these aspects: Reinforcing Best Practices.

Getting started with DITA

Most writers will be familiar with structures and templates, styling, categories and document identification, and crafting abstracts or briefs. DITA, as an open international standard, does take these aspects to a new level and constrain the writers to a certain level. The key is to understanding topic-based authoring (or modular documentation) will require the technical authors to:

Understanding topics

Topic-based writing should be easy to grasp for authors who are familiar with:

Once the topic type is established, the writer follows the expected information derived from the type. This structure is based mostly on common sense and best practices from the technical communication field.

Using tags instead of style to add meaning to text fragments

XML, as HTML, is a tag language. This means the text can be enriched with value-add information. Most authors will not write these additional tags manually. Topic templates and easy-to-use interfaces provide clickable actions for the authors to select and apply the right tags.

Most writers using a style guide such as the Microsoft writing style guide or editorial style guides use styling to enrich the value of the content or convey the objective of a content. A quote would be in italic whereas, in DITA, the writers will select the <cite> (or <longquoteref>) element.

Within the architecture itself for instructional topics, for example, to convey ordered steps in a task, the phrase Step 1. Create a new task topic, could be written in XML (or HTML) within a paragraph (p) element:

<p>Step 1. Create a new task topic.</p>

This is interpreted as a paragraph, but there are no other elements to state this is an instruction. The author has to add numbers to follow the flow and will need to adjust each time the test ‘Create a new task topic’ is used in another context or series of steps. DITA, on the other end, will take the semantics further by adding more details, such as:

<steps><step><cmd>Create a new task topic.</cmd><step><steps>

This is interpreted that the text is a command within a step, included in a series of steps in an instructional topic. Because the style sheet is separated from the content, the numbers and keyword (step) are added automatically by the XML editor and inserted at publishing.

Within DITA, signal words for safety information, notes, legends, will be added automatically and numbered by the XML editors and the publishing process.

Categorizing and labelling for product and information identification

Whatever their industries, every writer relies on documentation identification and product identification. These are two important parts of labelling content. When switching to DITA, that information should be inserted at the topic or at the collection level. In most cases, the task of choosing which identifiers are required and how they should be transferred in DITA will be taken by an information architect or a senior DITA expert.

This is really a matter of mapping the current identification requirements and enriching the topics with all required identification when they are used for different products.

Labels and catalogue information are part of a topic’s or collection’s metadata. Metadata allows content to be filtered, sorted, processed, and otherwise manipulated. Choosing accurate labels will result in more flexible documents.2

The end result is to provide machines and processors ways to properly identify content and apply search optimization, facets and manage product identification.

Abstracts and briefs to match web-writing best practices and provide quick recognition to end-users

Most writers with experience in web writing or journalism will know about the inverted-pyramid method. The method not only makes content more accessible; it also helps with search engine optimization and complies with web accessibility guidelines.

The inverted pyramid refers to a story structure where the most important information (or what might even be considered the conclusion) is presented first. In this case, the first paragraph, often found right after the title, helps advanced users understand the key points, and all users make a choice whether this particular topic will provide them with the answer they are looking for.

Short descriptions are hard to craft. They should be short, focused on the main points in the topic itself, they are not an expanded view of the title, nor glue text.

Example of a bad short description for a topic called Eco Printing:

The explanation below is on the eco-printing procedures for the eco printing.

Example of a better short description for a topic called Eco Printing:

The Eco function cuts toner consumption and paper usage. The Eco function allows you to save print resources and lead you to eco-friendly printing. If you press the Eco button from the control panel, eco mode is enabled. The default setting of Eco mode is Multiple pages per side (2) and Toner Save.

Example of a good short description for a topic called Eco Printing:

Use the Eco function to save paper and toner. Press the Eco button from the control panel to enable the eco mode. The default settings are Multiple pages per side (2) and Toner Save.



This blog was originally published in CIDM’s newsletter CIDM Matters.

Future articles will discuss the next two aspects of learning DITA: Adopting New Practices and Letting Go of Old Practices.

Sources

Amy Schade, Inverted Pyramid: Writing for Comprehension (online), Norman Nielsen Group: https://www.nngroup.com/articles/inverted-pyramid/

Keith Schengili-Roberts, IXIASOFT and Joe Storbeck, JANASShort Descriptions Shouldn’t Be a Tall Order: Writing Effective Short Descriptions (online), CIDM:
https://www.infomanagementcenter.com/product/short-descriptions-shouldnt-be-a-tall-order-writing-effective-short-descriptions/

Tony Self Dr., DITA Style Guide, Best Practices for Authors (online), Scriptorium Publishing:
https://www.amazon.com/Dita-Style-Guide-Practices-Authors/dp/0982811810

Microsoft writing style guide (online), Microsoft:
https://docs.microsoft.com/en-us/style-guide/welcome/

Nolwenn Kerzreho, Training technical communication students in structured content using DITA, in Current Practices and Trends in Technical and Professional Communication, ISTC.
https://www.amazon.com/Current-Practices-Technical-Professional-Communication/dp/0950645990/

1 A topic is a small, self-sufficient piece of information, with a clear objective and a set structure.

2 Dr. Tony Self in The DITA Style Guide, Best Practices for Authors.

Blog AUTHOR

Nolwenn Kerzreho
Technical Account Manager at IXIASOFT

Nolwenn Kerzreho is the Technical Account Manager for Europe for IXIASOFT and has over a decade years of experience in the technical communication industry. She holds a Master’s degree in Technical Communication, Translation, Terminology and Project Management.
An international speaker at leading events and academic colloquiums, Nolwenn teaches at the European Master in Translation at Université Rennes 2, where she introduced DITA in 2009. Based in France, Nolwenn has international work experience in the chemical, Telecom, language, and high-tech industries.

You can connect with Nolwenn on Twitter @nolwennIXIASOFT


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

Managing your own company’s content and documentation process is no easy feat, to say the least. Now imagine integrating and managing content from multiple company acquisitions and exponential product growth. And to add salt to the wound, the inherited content exists in all shapes and forms, making the task to unify and deliver it to customers that much more difficult. Sounds like a nightmare? Well, this is exactly what happened at DocuSign.

Gone are the days when DocuSign was a single-product company. Subsequently, they had to rethink and scale their content operation strategy and the tools they use to author, manage and dynamically publish self-serve content on modern platforms.

Delving more into the problem

DocuSign started off with a fairly common problem. There was a lot of product content that was being created such as user guides, quick start guides and release notes, all of which needed to be managed efficiently. As DocuSign grew by way of acquisitions, more and more content started to appear with its own set of requirements and issues.

In the end, DocuSign was left with content with inconsistent standards and various levels of content definitions. And to further complicate things, the source content was unstructured and delivered in Word, HTML, PowerPoint or something totally different.

Sure, DocuSign had some methods in place for publishing content, but it was mainly a system that required manual handoffs and a lot of time waiting for server pushes. And by the time the content reached the customer, there was a sense of disconnect, as there was no real path to navigate the content or an intuitive way to move between topics.

DocuSign sets its sights on solving the problem

Something had to be done about this and fast. This is when Dusty Clark and Deana Falk and other members from DocuSign set out to totally revamp their content operation strategy.

“In order to build toward an enterprise content experience, we needed to look at the entire journey and start connecting the dots.” Says Dusty Clark, Senior Manager of Content Operations at DocuSign.

DocuSign had to look at how they author content and the experience they provide to authors. They also had to look at how they publish and use metadata to support automation and personalization. And on the display side, they needed to analyze how customers can better find content and self-serve those needs.

“As we started to think about those foundational elements, we wanted to think about the full content experience starting with our author experience all the way through to our customer experience.” Says Deana Falk, Senior Information Architect at DocuSign.

DocuSign also had to address the problems surrounding findability and discoverability of their content, keeping in mind its goal of enhancing personalization via content profiles. Additionally, DocuSign looked at some other channels to deliver content to enhance user experience.

Systems used to assure success

DocuSign prioritized its systems with the long-term customer vision in mind. Before they were able to get to things like context sensitive information and product help, they needed to have a scalable authoring infrastructure in place.

DocuSign chose DITA implementation with IXIASOFT Component Content Management System (CCMS) to help it author, structure, standardize and manage its DITA structured content. The next step was to implement the Zoomin publishing platform to help aggregate content and use metadata to help them deliver content in various forms and on various platforms.

With those pieces in place, DocuSign was able to create a more personalized on-demand customer self-serve experience. It also provided DocuSign with the flexibility to use alternate display platforms or to modify content allowing them to publish it outside DocuSign’s current platform when necessary.

The proof is in the pudding

The next phase in the process was to validate these content experiences in reference to the new systems that were deployed. DocuSign wanted to validate these systems to ensure that the foundation that they were building truly improves the overall content experiences for both its authors and customers.

DocuSign looked at some KPIs they could track for both those experiences. They focused on average publishing time for their author experience and a usability score for their customer experience. For the authoring experience using IXIASOFT and Zoomin, DocuSign was able to reduce the average publishing time drastically; from approximately 1.5 hours to just 5 minutes to publish a single publication.

When testing the customer experience, DocuSign decided to create a proof-of-concept site using Zoomin’s documentation portal. DocuSign then executed an unmoderated usability test with approximately 30 customers. They were given a task to locate a single topic on DocuSign’s existing portal and on the Zoomin documentation portal. The result was clear; a single task that took two minutes on DocuSign’s existing support center only took 55 seconds on the Zoomin portal.

And lastly, a system usability scale showed significant increase in overall usability score. DocuSign’s support center was ranking at 76%, while its proof-of-concept Zoomin documentation portal ranked at 90% with those same customers.

These numbers assure that DocuSign made a sound investment when choosing to revamp their content operation strategy to accommodate for an influx of new content all while enhancing the user experience of their authors and customers.



This blog was originally presented as a webinar by Dusty Clark and Deana Falk from DocuSign, and sponsored by our technology partner, Zoomin.

Blog AUTHOR

Phil Masella
Marketing & Communications Manager at IXIASOFT


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

Many writers work with a style guide. This guide includes a comprehensive set of rules and guidelines to help writers create and deliver high-quality content. However, it is the  responsibility of the writers to remember and implement these rules, which requires time and effort.

Authoring assistance, on the other hand, is instant. In other words, writers can focus on creating content, while the software verifies it, and prevents errors.

In this blog, we will highlight some strategies on how to successfully implement authoring assistance software, and ensure user buy-in.

What Is Authoring Assistance?

Authoring assistance is a type of software program that supports writers in creating understandable, consistent, and quality content. It generally provides the following features to authors:

This feature supports the consistent use of terms specific to the company and its industry.

The language check feature helps prevent linguistic errors such as grammatical errors or spelling mistakes.

This feature makes it possible to optimize content reuse with authoring memory, and can lead to significant time saving.

Authoring assistance can also help enhance the follow-up processes such as translation. More understandable content in turn makes translation smoother, with less back-and-forth between translators and writers. Consistent reuse of sentences and phrases can also increase translation memory and decrease translation costs.

The Benefits of Authoring Assistance

When implementing authoring assistance, a company should define specific goals, and communicate them to users within the company. Here are some common goals:

Customer journey often starts at different points: i.e., marketing content, service documentation, etc. Establishing a tone of voice to use consistently across communication channels will make the company stand out and help it differentiate itself from the competition. It will also create a smoother experience for users.

As mentioned earlier, a consistent terminology allows a company to stand out. Writers should use the same wording when creating different types of content to avoid confusion and ambiguity.

Authoring assistance can help cut translation costs. For example, content reuse will reduce the volume of content needing translation, and consequently reducing  translation costs.

There are many other goals that can be achieved with authoring assistance, all of which ultimately increase overall content quality.

Authors receive feedback on how to write in a clear and convincing way.

Over time, fewer spelling and grammar issues occur. The writing style is enhanced, and is consistent with the company’s style guide.

While authoring assistance requires an investment, its features enable the company to save costs and recoup expenses. Content reuse, for instance, speeds up the review process. Writers can reuse sentences created in the past that have already been reviewed.

Authoring assistance, like all software, has its limits. The system generally does not have world knowledge. This means that it only looks at the linguistic aspect of content, not the meaning of sentences. Moreover, this tool is made to assist writers in creating content, but is not aimed at replacing them.

To gain user buy-in, it is essential to communicate the software’s benefits and limits clearly so that users are aware of how the software can support them in their daily tasks.

How to Implement Authoring Assistance in your Organization

The implementation of authoring assistance software should be phased. Before diving into a  phased implementation strategy, here are some common errors to avoid when introducing authoring assistance.

Users may become frustrated and discouraged if faced with countless messages when contributing a small portion of content. When introducing the software, it’s better to select a small set of rules that is applicable to the content and users.

Similarly, focusing on the most critical issues as a first step is a smarter approach. If the main goal is to reduce translation costs, starting with authoring memory would be best. By implementing features gradually, users can see their value, and provide constructive feedback. This makes user buy-in more likely.

As much as possible, the system should be set up to only display messages that are relevant for authors; otherwise, they lose time confirming messages, which can threaten user buy-in.

The people who will work with the authoring assistance software are not always involved in the decision process (i.e., tech writers, SMEs, and marketing). It is important to speak with them, and make them aware of the goals to be achieved with the software, as well as its limits (expectation management).

Phased Implementation: A Path to User Acceptance

Authoring assistance is an investment, and you should carefully plan your implementation strategy to fully benefit from it.

Phased implementation is an interesting approach, as it suggests to first introduce the system to a group of key users within the company, and grow progressively.

Below are the essential aspects of a phased implementation:

When deciding which rules to implement, you should examine your style guide to see which rules are the most important. As a trial, you can pick a set of representative documents and have them checked with the authoring assistance system. You may realize certain rules of the style guide were never followed, and decide whether you should enable them.

Choose a specific set of rules to help writers focus on the essentials, while they are getting familiar with the system. In time, your content quality will increase. Authoring assistance provides reports on the number of messages filed by the software; fewer messages issued is an indicator of better content.

There are often different profiles of writers within a company. Some people may contribute content occasionally and are not experts. Having a default set of rules, as well as an optional stricter rule sets, is beneficial for various types of writers. More experts and advanced profiles look at the stricter rule sets, while others use the default one.

Over time you will be able to move toward your full style guide.

Check in regularly with users, and listen to their feedback. It is critical for  a successful implementation of authoring assistance – it cannot happen without user buy-in. It is important that they see the software as a tool to support them in delivering quality content, and not a constraint.

Promote one or several key users who have knowledge about the software, and who can address questions about it, and provide feedback to other users.

Check out IXIAtalks episode 19 for a demo of how to put these guidelines into practice.

Introducing authoring assistance should be a team effort. You cannot get the most out of your system unless you work with your users to incorporate it gradually, safely and efficiently to enhance their content creation process. Careful and thoughtful preparation will pay off in increased content quality, reduced costs, and increased writer efficiency.



This blog was originally presented as a IXIAtalks webinar by Alexander Becker from Congree. You can find the webinar here.

Learn more about our IXIAtalks webinar series.

Blog AUTHOR

Amandine Mondélice
Marketing Coordinator at IXIASOFT

Ixiatalks panelist

Alexander Becker
Head of Sales at Congree Language Technologies GmbH

Alexander Becker is Head of Sales of Congree Language Technologies GmbH. The graduate linguist has been with the software manufacturer since 2012, providing customers with advice on the subject of authoring assistance.


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

MONTREAL (PRWEB) January 18, 2021

IXIASOFT addresses a growing market of non-DITA authors, while reinforcing its leading position in the global CCMS market.

IXIASOFT, a leading DITA CCMS software company based in Montreal Canada, announces today that it has acquired AuthorBridge from Stilo International, a UK-based provider of software tools helping organizations automate the conversion of content to XML.

Developed in collaboration with IBM, AuthorBridge is a DITA-based web editing tool providing SMEs with a guided and fluid authoring environment. AuthorBridge is specifically designed for users with no knowledge of DITA or XML. This tool has helped organizations efficiently implement authoring for professionals in marketing, engineering, training, and support.

Increased time-to-market pressures has led organizations to rely on various internal resources to produce high-quality content. And this trend has caused a growth of non-DITA authors in the CCMS market. The addition of AuthorBridge inside of IXIASOFT’s product suite will allow it to offer supplementary solutions to better address this new market segment, while strengthening its global position in the CCMS marketplace.

IXIASOFT will continue to offer advanced editing capabilities for DITA experts through its current product integration with the leading XML editor, Oxygen.

“We are pleased to add AuthorBridge to our IXIASOFT product line. This is a great opportunity for us to grow our product offerings and further address a segment of non-DITA experts that need to contribute their knowledge quickly and easily,” says Eric Bergeron, CEO at IXIASOFT. “And with our CCMS moving toward a web-based application to offer authors an enhanced user experience, this acquisition is aligned with our overall vision to provide comprehensive and user-friendly CCMS products to the techcomm industry.”

“AuthorBridge was developed to offer an intuitive authoring experience for subject matter experts with little to no knowledge of XML,” says Bryan Tipper, CEO at Stilo. “We are incredibly proud of its market acceptance, but have realized it would be best leveraged if offered through a complete CCMS solution. We are very pleased that IXIASOFT has decided to continue with its product development and look forward to its future success.”

In addition to this exciting acquisition, IXIASOFT is actively deploying its solution to new customers and preparing the release of IXIASOFT CCMS v6.3 on January 28, 2021. IXIASOFT is also planning its upcoming annual CCMS Link User Conference scheduled for March 23 to 25, 2021.

About IXIASOFT:

Founded in 1998, IXIASOFT is a trusted global leader in the XML content management software industry. Its signature product, IXIASOFT CCMS, is an award-winning, end-to-end component content management solution (CCMS) used to produce and manage DITA structured technical documentation. IXIASOFT CCMS has been deployed by industry leaders like Abbott, ARM, Ericsson, Komatsu, Mastercard, Qualcomm, SAP®, and Toyota.

About Stilo International:

Stilo develops tools to help organizations automate the conversion of content to XML and build XML content processing components integral to enterprise-level publishing solutions. Operating from offices in the UK and Canada, Stilo supports commercial publishers, technology companies and government agencies around the world in their pursuit of structured content.

For more information, visit www.stilo.com/about.

Press Release Contact

Caroline Couvrette, VP Sales & Marketing
IXIASOFT Technologies Inc.
Email

Read the original press release here.

On October 22nd, IXIASOFT’s Head of Marketing and Communications Sydney Jones interviewed ARS Logica founder Tony White about the current trends in the CCMS/DITA marketplace. The interview tackles questions such as how COVID-19 has impacted the technical documentation industry, and exposes important considerations to take into account when selecting a CCMS. It also reveals some of Tony White’s key findings in his 2019 analysis of the CCMS industry.

Tony White has over 20 years of expertise in content management. In the past few years, his interactions with customers and manufacturers led him to start the Compass Guide as an answer to the increasing demand of information on CCMS, a system that was previously only in the realm of very technical sectors. The trends have evolved, and there is now increasing interest from marketers, who also happen to be decision makers.

So Tony, what inspired you to conduct this research on CCMSs?

The Compass Guide to Component Content Management Systems is a recent development. In fact, my background as content management analyst is for the most part in the unstructured content side of things. However, in the past few years, several reasons inspired me to start evaluating CCMSs:

The first reason was that the marketplace was starting to show interest for CCMS evaluations. Organizations would request CCMS platform comparisons, and research on the state of the market in order to decide what CCMS was best for them to orchestrate a smooth handoff of their structured content between their Digital Experience Platform (DXP) and a CCMS. No analyst firm was publishing this type of report then.

The demand also emerged from manufacturers of the technology, who were looking to point their prospects to research.

What decided me to move forward is that DXPs and CCMSs complement each other greatly. As they are going through the customer journey, customers are not aware of the handoff happening in the backend between structured and unstructured technology systems, which further demonstrates how well the systems function together.

In addition, while the CCMS technology used to be exclusively in the realm of technologists, it is becoming more relevant to non-technical business users. Organizations are more and more required to incorporate technical content, product information, and more detailed precisions in the customer experience they deliver.

Why in 2020 is it beneficial to choose a CCMS vs. a CMS?

The first differentiator for CCMSs is their level of DITA compliancy. DITA is an open structured standard used to manage, create, and publish content. DITA enables a CCMS to manage structured content more efficiently than a CMS, which is an unsatisfactory substitute.

An important thing to keep in mind is that many companies benefit from using both systems, so it is not necessary to choose one or the other.

The recent pandemic context has made it even more valuable to invest in a CCMS, as there has been an upsurge in reliance on digital as the sole point of customer interactions. Customers are less likely to call or visit businesses in person, and need to be able to access technical information through the digital experience. Companies where CMSs and CCMSs are well integrated have been put ahead of the others.

What is your process for evaluating a CCMS?

The process follows the framework of the sources of information that appear in the Compass Guide. It consists of using information that has been collected from several sources:

  1. Vendor Questionnaire

The vendor completes an exhaustive questionnaire of about 200 questions relating to the company, its product, customers, verticals, history, wins and losses, revenue, etc.

The vendor questionnaire provides a reference point to go back to while producing the report and ensures the information is up to date.

2. Customer Interviews

Customers interviews aim at validating the responses provided to the vendor questionnaire.

3. Implementation Monitoring     

In this step, I verify that vendors’ claims and information from the market are accurate. For instance, I look at whether the product roadmap issued to me the previous year has come into reality, and if features and functions that were listed in it are now available with the product.

4. Product Documentation

Product documentation provides in-depth details about the product. It is often included in the resources section of vendor websites and gives the final confirmation of what features/functions made it into a particular version of a product.

5. Ars Logica’s Knowledge Base

My 20-25 years of career in content management have allowed me to build up a broad and wide knowledge base, which is transcribed into the reports.

6. Hands-On Product Testing

Vendors often provide me with a sandbox to test the product. I use it to go through use cases from customers to see how a particular platform addresses certain requirements, and thus acquire experience in using the product.

Can you tell us more about the 2 axes you use to evaluate a CCMS?

I use a two-plot axis with respectively business criteria (plotted on x-axis), and technical criteria (plotted on y-axis). Under each of these, there are broad categories, which are combined into a single score:

Business criteria

Technical Criteria

The market is still behaving like an immature technology market, although it is about 25 years old. Because it has not reached a certain threshold from a monetary point of view, the larger technical systems integrators have not become interested in this as a coverage area they can provide services for. Therefore, the strength of the technical ecosystem, especially compared to DXPs, is low but important to look at. It is critical to check if a service provider is going to be able to do your implementation.

Let us look at a real-case example of business criteria, and technical criteria scoring with IXIASOFT CCMS, extracted from the latest Compass Guide.

Business Criteria Scoring

Technical Criteria Scoring

IXIASOFT performs consistently across the scoring criteria. This is in part because it has over 20 years of experience in the industry and is the first 100% DITA-compliant CCMS vendor.

It is quite rare for a vendor to have a 9 in two categories. I find that IXIASOFT CCMS is an uncommonly capable technical platform from a historical and market perspective.

The technical ecosystem is lower than others. It relates to the size of the company. When compared to larger companies and vendors, the products do not perform as well, but the strength of their technical ecosystem is higher because they have larger partners and more of them.

How did you come up with these different categories to evaluate CCMSs?

I have received a lot of feedback from CCMS marketplace vendors and manufacturers about the need for these reports. The sources information I gathered, and these conversations gave me initial input as to what these categories should be. I then narrowed it to something manageable. It was important in this process to look at how features are related and who is going to use them to categorize them.

Can you comment on trends in the DITA CCMS marketplace?

Even though the CCMS technology has been around for 20+ years, it was first in the realm of highly technical users only. Consequently, CCMS platforms vary wildly in their feature function sets, and in the sophistication of the products.

In recent years, DITA has become more relevant to digital marketers in terms of the benefits it brings, and what it allows them to do in terms of content management. As a result, the ways that CCMSs are incorporating this feature set into the user interface is relevant to them. In addition, the ease of use of the DITA feature functionality is improving dramatically.

Finally, COVID-19 is forcing customer interactions to be digital. Companies that have well integrated DITA CCMSs and DXPs are responding better, and allowing for a better e-commerce experience.

Which industries are more likely to benefit from a CCMS?

Regulated industries are the ones that benefit the most from a CCMS. The more regulated, the more the benefits. Examples include manufacturing, aviation and aerospace, healthcare, financial services, and any industry that relies heavily on technical content.

An increasing number of industries now need to seamlessly combine technical and non-technical content as part of managing customer journeys that needs to include an increasing amount of content, and content types.

How has COVID-19 affected technical documentation as a whole? Or individual industries?

COVID-19 has forced the exclusive digital nature of interactions. As a result, technology is the unique way customers can get information from companies. If the information is structured such as SKU, product number, warranty, or else, the need of a CCMS is critical.

This puts a spotlight on the interaction between structured and unstructured content management systems.

What were some of your conclusions based on the evaluation of IXIASOFT CCMS?

Let us first look at IXIASOFT CCMS’ key strengths:

IXIASOFT ranks first or co-first in many of these categories.

Looking into the limitations, IXIASOFT CCMS has a very strong technical ecosystem, although it is not large compared to some competitors. This relates to its limited market presence compared to the other top-tier platforms, which are bigger companies. Finally, IXIASOFT CCMS might not be a right fit for companies who are not 100% DITA-compliant, or do not have a project to become so shortly.

What are some requirements of customers for whom IXIASOFT might be a best fit?

Full DITA compliance would be the first criteria:

Number two is multi-channel publishing, which is simultaneously a strength, and requirement. Dynamic content delivery relies on content being format free so that the destination is not constrained.

The third one is robust taxonomy and semantics support.

To download the full report, click here.

What does the future of the CCMS marketplace look like?

First, the integration of structured and unstructured content solutions will improve. This will be an initiative from the vendors themselves, through more partnerships between structured and unstructured vendors. Companies that have traditionally offered web CMSs will increasingly offer CCMSs. Furthermore, as implementation providers witness the growing synergy between structured and unstructured platforms, they will start offering specialized services.

Then, I foresee that companies that are producing the most sophisticated platforms will be doing so at a brisker pace than companies that have developed simpler platforms, which will continue widening the gap in sophistication between the top-tier platforms and the rest of the market.

Finally, the large system integrators that were not interested in this technology in the past will grow interest for it, as it crosses a certain revenue threshold. This will provide an improved partner landscape.

Can you predict any future trends with DITA or CCMSs?

I have already started to see the first one come true, which is that artificial intelligence and machine learning are starting to play a major role in vendor roadmaps, especially in the area of predicting customers behavior and providing the right customer journey based on it.

This trend combined to DITA will finally make a wide variety of “self-service” attempts successful.

CCMS vendors will also start to differentiate within particular verticals over the next 18-24 months by offering specialized services by industry, such as financial services or semiconductor.

Lastly, digital marketers will not only become the primary buyers of CCMS, but they will also be the primary drivers of the CCMS market evolution.



Thank you to Tony White for sharing his findings and comments on the present and future of the CCMS/DITA landscape, and tips on how to choose the right CCMS. The full Compass Guide to Component Content Management Systems is available here.

This blog was originally presented as a IXIAtalks webinar with Tony White from ARS Logica. You can find the webinar here.

Learn more about our IXIAtalks webinar series.

Blog AUTHOR

Amandine Mondélice
Marketing Coordinator at IXIASOFT

IXIAtalks panelist

Tony White
Founder at ARS Logica

Tony has over 20 years of experience as content management analyst. He assists companies in choosing the right digital experience platforms and content management systems for their organization. Tony also leads corporate education and workshops, monitors implementations, and assesses the quality of service provider services.


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

Finding the right information can be a nightmare for users in our increasingly digitized world. A simple solution is taxonomy.

But what is taxonomy, and why should you use it?

In this blog, you will learn how to use taxonomy, and how it can improve user satisfaction.

What Is Taxonomy?

According to Bob Bater, the author of ‘’Practical Taxonomies,’’ a taxonomy “Formalizes the hierarchical relationships among concepts and specifies the term to be used to refer to each; it prescribes structure and terminology.’’

Think of taxonomy as a way of classifying things or concepts by hierarchy. When creating a taxonomy, it is important to define taxonomy terms to ensure an accurate classification of concepts.

Below is a simple example of a taxonomy:

“Star,” “planet,” “TNO,” “satellite,” and “asteroid,” are all types of celestial objects.

Once a classification is created, the values which are added to the classifications might evolve overtime.

For instance, in the automotive industry, new car models like SUVs have emerged over the past 50 years, and are now classified under “car models,” next to ‘mini-vans”, and “convertibles.” Other car models have been discontinued.

Therefore, taxonomies can evolve in the sense that customers’ needs also change, and organizations need to adapt classifications to reflect it so that customers are informed correctly. The overall taxonomy structure; however, remains the same.

Here is a real-life example of taxonomy on NASA’s website. It shows several facets of NASA “Missions” created by tagged content on the website.

The elements below ‘’Missions’’ are classified directly under it.

By adding taxonomy to content, the user can easily find it, which in turns allows one to leverage content with dynamic delivery while enhancing user experience.

Where to Find Taxonomy in Your Organization?

Quite often, taxonomy already exists in organizations, but people do not know where to find it. Any company that has a website within which information is classified owns one or more taxonomies. These taxonomies can be owned by different people, which makes it essential for these different teams to communicate with each other.

Here is where one can find taxonomy in an organization:

The way classification is handled depends on the organization’s size. In larger organizations, the process is more formal and involves representatives from several divisions. In small organizations, a few people are responsible for maintaining it.

Communication between stakeholders is essential in both instances to ensure that classification values are used effectively within content and for delivery.

Index terms are subject descriptions that the author makes available to help readers navigate the content. They can serve as a great resource to start a taxonomy or to help validate all the ways people look at content in your classification.

Keywords and tags are assigned to content.

Marketing, product owners, and website managers are generally the people who have access and ownership of taxonomy.

Dynamic Delivery: a Taxonomy Use Case

User experience is at the core of taxonomy. In dynamic delivery websites, users can easily access the content they are looking for.

DITA, a proven open-structured standard, is commonly used to build dynamic delivery websites. DITA topics are dynamically created based on the taxonomy classification system used. All the concepts under a taxonomy are grouped together, making navigation and search intuitive. This further stresses the importance of using the right terms when starting a taxonomy, and to have the right governance in place.

The richer the taxonomy— and the more specific the application to granular content units—the more sophisticated the user experience will be.

Which Taxonomy Values Should You Use?

Taxonomy values include numerous grouping options. These include the following:

The most crucial thing to have in mind when creating terms for a classification is consistency. Clear and consistent tagging will guarantee a uniform experience for customers.

In a word, the most robust taxonomies are designed based on how the end user is expecting to use them.

The example above uses audience taxonomy values: “For Media,” “For Educators,” and “For Students.” These are different facets of NASA Audiences that are dynamically created based on the content, and on what the taxonomies have within them.

Taxonomy in Action

Taxonomy aims to power up user experience. There are various ways to use taxonomies:

In addition to classic navigation through menu bars, taxonomy enhances search engines. One way of achieving this is by having keywords in a taxonomy.

Note that a keyword can exist in multiple classifications. In this case users should be able to filter search results using faceted search to refine search criteria with certain values and categories.

Menus at the top of websites are good visualizations of the taxonomy hierarchy that we see in the taxonomy management tool.

Taxonomy can be more complex and sophisticated to create different and tailored user experiences for different user types.

Where Does Taxonomy Live?

Taxonomy can live in DITA content.

Maps and topics both have <metadata>. Within metadata are the <category> and <keyword>. Taxonomy terms live in the <category> or <keyword>.

Once taxonomy terms and governance have been selected, it is up to the tool to implement taxonomy on your dynamic delivery website.

With a CCMS like IXIASOFT CCMS, you can tag content, and put taxonomy values into <category> or <keyword>. Once you generate output and get the HTML files, the dynamic delivery platform will read them.

Pitfalls to Avoid

Taxonomy should be categorized by hierarchy.

Keep it all in one place, even if it is not with your team.

Be sure to leverage whatever your company already has.

Taxonomy terms can be used in different places such as websites, help applications, and other outputs. Taxonomy should be built with regards to the method selected.

Communication within teams and the overall organization is key.

You’ll need all the help you can get.

It’s all worth it.

Building taxonomy is a journey: it takes time, and requires people to support you along the way. The return on investment, however, makes it a worthy cause. Not only will your organization have a consistent way of structuring content, but users will also benefit from a significantly improved experience.



This blog was originally presented as a IXIAtalks webinar by Boris Roberto Aguilar from IXIASOFT and Amber Swope from DITA Strategies Inc. You can find the webinar here.

Learn more about our IXIAtalks webinar series.

Blog AUTHOR

Amandine Mondélice
Marketing Coordinator at IXIASOFT

IXIAtalks panelists

Amber Swope
DITA Strategist at DITA Strategies Inc

Amber is an internationally recognized expert on the Darwin Information Typing Architecture (DITA). She specializes in helping teams develop their information architecture and implement DITA. With over 20 years of experience in the information development field, and 15 years of DITA expertise, Amber helps teams design and optimize their environments to improve efficiency and reduce costs. When she’s not busy helping to change the world with XML, she can be found playing soccer and enjoying her hometown of Portland.

Boris Roberto Aguilar
Customer Success Manager at IXIASOFT

Boris is the customer success manager at IXIASOFT. Based in Toronto, he has over 11 years of experience in DITA and technical documentation. Boris is skilled in PHP, Mobile Applications, Software Documentation, HTML, and Scrum, and is highly experienced in enterprise systems deployments. His favorite hobby is photography, and he also hosts a podcast.


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

As most of you know, DITA North America and DITA Europe are two of the premier conferences for content creators working with DITA. Normally, these conferences are held in the spring and fall respectively, but like so many in person gatherings, had to be postponed this year. Leave it to the CIDM team to see this not as a loss but as a challenge to create a new kind of virtual conference that will be a benchmark for virtual conferences going forward.

ConVEx is the fruit of CIDM’s labour to adapt to professionals’ new working reality, and their willingness to deliver not just a conference, but a Virtual Experience, as they call it.

A New Kind of Conference

ConVEx was conceived not as simply a substitute for DITA North America and DITA Europe, with presentations streamed live instead of attended in person, but as a completely new experience. Several of us here at IXIASOFT attended and participated in ConVEx events and we’d like to share some of our impressions with you.

Our first impression was…what a lot of fun! Our second impression was…what a lot of work! A virtual conference is a lot more work for everyone, organizers and participants alike. A physical conference and its events exist whether you participate in them or not. You show up to the venue. The conference rooms are there, presenters show up and give presentations. Vendors show up and have booths and exhibits. There’s a cocktail hour and other social events. All of this happens regardless. But a virtual conference only exists if people participate. Otherwise, there is no there there, to quote Gertrude Stein.

ConVEx was definitely a success in this respect, so a big hand to everyone who participated, whether by recording presentations, participating in Candid Conversations, showcasing their talent, or being an enthusiastic listener and questioner.

The Logistics

ConVEx was organized around a Main Stage, where keynote presentations and other social events took place. Like an in-person conference, there were various tracks for different subjects

In the weeks before the conference, presenters (including myself) recorded our presentations. This experience was incredibly pain-free. We booked a time slot in advance and at that time, logged in and were helped through the process by an A/V professional to ensure the best quality recording. All of these presentations were then gathered into the ConVEx Library, which was available online, with presentations sorted into several tracks: Collaboration, Content Strategy, Management, Reuse, Use Cases, and User Focus. Attendees could view any presentations that interested them.

Benefits of a Virtual Event

Of course, while it can be hard to be as attentive and enthusiastic about a recorded presentation as an in-person presentation, the great advantage to recordings is that you can watch them whenever you like. And how many of us have looked at an in-person conference agenda only to discover that there are two or three presentations we really want to attend, but they all take place at the same time! This is another of the advantages of a virtual conference… there’s no need to choose. You can attend every single presentation that interests you.

One of the best parts of an in-person presentation is the chance to ask questions afterward, whether during the Q&A period immediately after the presentation, or later, as you find yourself at a lunch or dinner table with the presenter or perhaps in the bar downstairs….While not quite the same, this experience was part of ConVEx as well. Most recorded presentations also had a scheduled live Candid Conversation where anyone wanting to chat personally with the presenter could drop in and ask questions and contribute thoughts or war stories.

I hosted a Candid Conversation around my presentation, “Don’t Forget the Tech Writers” and was pleased to see some familiar faces there and even more pleased to hear everyone’s comments. We chatted pleasantly for the full hour, which is generally longer than we would have had to talk after an in-person presentation or even during other in-person conference opportunities.

Candid Conversations Hosted by IXIASOFT Customers

Other great candid conversations were led by IXIASOFT’s customers such as Danfoss Power Solutions, SAP, Allscripts, Mastercard, KLA and AMD.

Jill Sheffield of Mastercard shared how her team transformed its content strategy in order to deliver targeted content to a global audience, and elevated customer experience, all while improving overall efficiency in her ‘Mastering Efficiency and Impact in Content Creation and Delivery’’ presentation.

Vasanth Vaidyanathan and Vidhya Kameswaran from KLA taught the audience how to measure technical writers’ productivity in a very early slot for those tuning in from North America – 3.30AM EDT.

One of ConVEx particularities was in fact that presentations were broadcast across 8 time zones, including IST. Luckily, most presentations were recorded, and will be uploaded on the event’s platforms in the coming weeks, allowing registrants to catch up on presentations they missed for up to one year.

In addition to the Candid Conversations, there were also Test Kitchens, just like at DITA North America and DITA Europe, where vendors could showcase their solutions.

IXIASOFT’s Nolwenn Kerzreho, Sharon Figueira, and Robert Bredlau invited ConVEx participants to get personal with one of IXIASOFT CCMS most appreciated features: the Collaborative Review which allows technical writers, contributors, and subject matter experts to attain efficient review while nurturing a strong collaborative culture, in their ‘’Remote Collaboration in a Challenging Environment’’ test kitchen.

How to Network in A Virtual Environment

Now, the one thing that is a bit challenging to replicate in a virtual conference is the vendor area. Vendors who attend conferences really count on foot traffic and the chance to meet folks and make those connections that while not bearing fruit right away, might come back months later as an opportunity. Despite the challenge, ConVEx also included an Exhibitor Hall. Each vendor approached their virtual “booth” a bit differently, but most featured a greeting video, brochures and other product information, links to additional resources, and contact information. There was also a monitored Slack channel where attendees could reach out directly to vendors whose products or services they were interested in hearing more about.

Here at IXIASOFT, we had a lot of fun creating a “bumper” video for our booth. We chose a scenic or iconic area of our respective home cities (and being as distributed as we are, there were a lot of cities to represent!) and flexed our directorial muscles by filming ourselves catching and throwing a piece of paper. Individually, it was a bit strange, but all put together it made a fun and rather touching video. In a way, that exercise represents what ConVEx and really, the last six months, have been all about. We’re having to do a lot more things separately and put it all together afterward, but the result can still be magical.

The DITA community is very tight-knit, and we always enjoy the social aspects of conferences and other get-togethers. ConVEx was no exception. There were many social activities, among them lots of food stuff, because who doesn’t like food?

Just to name a few things, attendees could take their pick of a beer tasting with Etteplan, a Happy Hour with Ryffine, several cooking shows with Comtech (Italian chili, almond tea cake), a coffee klatch with Jorsek, a DITA Map Sandwich with Mekon, a Salted Maple Pumpkin Smoothie with yours truly IXIASOFT and special CEO guest, Eric Bergeron, and topping everything off with Bailey’s Fudge & Irish Coffee from Miramo. If you were really following along at home, you’ve probably spent some extra time on the treadmill working off those “virtual” calories!

Other social activities included Handwriting Analysis with Zoomin, several games of trivia, and the talent show.

Boy, was the talent show fun! And quite impressive. I mean that. Lots of talent in this community. Many of us have known and worked with each other for years and we had no idea we were such accomplished singers, musicians, poets, impressionists, woodworkers…and, uhm, jugglers. The virtual nature of the talent show made some acts possible that would have been very tricky to pull off in person. For example, I did a short demonstration of turning a small wooden bowl. As I generally don’t travel with a lathe (very hard to fit in the overhead bins), there’s no way I could have done this at DITA North America. It was so much fun to see a new side of people and find out a little bit about what we do when we’re not DITA-ing.

My colleague Scott Kush says “It was nice to see customers, prospects, partners and IXIASOFT people just engage in the new normal for an hour – we definitely will do more in future shows.”

As you probably noticed, most of the social activities were sponsored by the conference’s vendors, all of whom spent a tremendous amount of time planning thoughtful and fun things we could all do in the “new normal.” That goes back to what I said earlier—that a virtual conference takes more effort on everyone to create the space and the interaction that normally just occurs with an in-person conference. I can’t mention all the vendors in this post as there were wonderfully many, but again, a huge hats-off to my colleagues at IXIASOFT and to everyone for the imagination and humor you all contributed to ConVEx.

In addition, IXIASOFT proudly hosted a Charity Donation contest, a good way to show appreciation to attendees for their presence, while giving back. Our two contest winners –Patricia Burrows of Rocket Software Inc., and Dana Aubin from Allscripts— each won a $500 donation to support a global charitable organization in their name.

Dana chose to donate to Amnesty International. ‘’I chose Amnesty International as the recipient of this generous donation because I strongly support their mission to protect human rights across the globe.”

Patricia chose to split her prize to support two organizations, World Wildlife Fund, and the IC of the Red Cross. ‘’I support the World Wildlife Fund as I appreciate their holistic view of environmental and conservation problems. I also chose to support the IC of the Red Cross and their incredible and difficult work in supporting people in some of the most underserved populations in the world.”

Final Words

Now to be completely fair, I have to mention one disadvantage of ConVEx (aside from the obvious one of not actually being together, but enough said there). When we go to a real conference, the expectation is that we are physically away from the office and although we might have to answer e-mails or do a few things throughout the day, it’s understood that we’re “doing the conference” during those three days. There’s no such understanding with a virtual conference and so listening to the presentations and attending the Candid Conversations and the social activities was actually in addition to everyone’s normal work day and activities. That makes it all the more impressive that so many people showed up and really participated to the fullest.

As CIDM has said many times, while ConVEx replaced several in-person conferences this year, their goal from the start was not merely to create a virtual substitute for those conferences but to create a completely different kind of event that stands on its own, takes advantage of the additional and different opportunities presented by a virtual environment, and continues to grow even after we can all come back together in person.

While I am surely not alone in hoping that DITA North America, DITA Europe, and all the other gatherings we enjoy so much can return in 2021 in the usual format, I also hope that ConVEx will continue to live on as well.

Blog AUTHOR

Leigh White
DITA Specialist at IXIASOFT

Leigh White is a DITA Specialist at IXIASOFT, where she works with product integrations,product design, and marketing communications. Leigh has spoken on DITA, content management systems content conversion, and DITA-OT plugin development at a number of industry conferences, including DITA North America, DITA Europe, Intelligent Content, Lavacon, Writers UA, DITA Netherlands, and Congility. She is the author of DITA For Print: A DITA Open Toolkit Workbook and a contributor to The Language of Content Strategy and The Language of Technical Communication. Leigh is also a member of the OASIS DITA Technical Committee.


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

The value of information developers is increasing in businesses across the globe. Their work plays a central part in customer satisfaction. Not only do information developers create content to support products and services, they build data that addresses  businesses goals, and the information development role in ensuring the success of product projects.

Information developers support teams in staying on track by making estimates, benchmarks, and by communicating them to team members throughout the project.

In this blog, you’ll learn how connecting the Content Life Cycle (CLC) to the Project Life Cycle (PLC) allows information developers to align their work  with the highest-level strategic goals and objectives of an organization, establishing strategic value.

Owning Your Strategic Role in the Organizational Structure

Information developers hold a pivotal role in organizations. For them to carry out their work successfully, it is important that other members recognize their added value. Here are a few ways they can demonstrate it:

Connecting the Project Life Cycle (PLC) to the Content Life Cycle (CLC)

The Project Life Cycle is what the project manager depends on to conduct successful implementation by making a framework for projects.

Information developers rely on the Content Life Cycle to guide their work. It corresponds to the process of content creation and communication management for this content.

These two life cycles are similar, but generally work separately. Drawing a connection between the CLC and PLC will further support information developers to demonstrate their business value, and attain successful project outcomes.

To do so, information developers must make a parallel between PLC and CLC for each phase of these cycles, and identify how CLC fits into the project.

1. Initiate

The first phase of PLC consists of deciding whether the project will be executed, based on the study of two documents:

If a project fails either or both profitability and feasibility tests, chances are the project team will not move forward with it. Conversely, a project that passes these tests will likely be assigned to a project team or project office.

During this phase, the information developer must identify everything they need to succeed the project, and ask for it.

This corresponds to the research phase at the CLC level. At the end of this phase, the information developer should be in the position to answer the question: ‘’What business problem does this project solve?’’

Other questions to ask could be:

As they collect answers, information developers integrate them to an initial estimate document. Data gathered from past projects will also make possible to estimate project overhead, with different scenarios, and feature work. Their findings will influence their work, and the project success. The file is then submitted to the project manager for approval.

2. Plan

Once the project is approved, the project manager designs a project plan. It guides the team to produce quality outputs, handle risk, and conduct their work properly while staying on time and on budget.

The project plan usually includes a statement of work, a resources list, a work breakdown structure, a schedule, and a risk plan. These documents aim at making the project viable.

In the Content Life Cycle, the planning phase consists of:

It is essential that information developers develop a content plan, a process, and KPIs to drive their work.

3. Execute

The execution phase of the PLC relies heavily on the planning phase. It is no longer possible to make changes to the costs, scope, and timeframe previously established. It entails building deliverables that respond to customers’ requirements. The project manager organizes its team by assigning them to certain tasks:

The tactical work then begins for information developers with the estimate, write, edit/revise, review, and publish phases of the CLC.

Information developers start attending the Program Increment (PI) planning, and sprints. During these meetings they gather information, contribute to the planning, and work on the project. Sprint reviews are the opportunity for IDs to feature their work with demos. This is also the time when they communicate positive progress, risks, and any obstacles to the project completion to team members and the project manager.

4. Monitor and Control

Monitor and control often occur at the same time as execution in the PLC. As the project is being executed, the project manager monitors how the team is doing in terms of project advancement.

In the CLC, information developers should  track their progress, and always maintain an up-to-date status . Although it requires additional time and effort, it is essential for IDs to know their progress and status, and alert product teams know if they identify any issue or if there is any change in scope as this will affect timeframe.

This phase enables tracking any cost or time variations, and ensures the project runs smoothly.
Note that while internal systems are set up to gather data (MS Project, JIRA, Trello, SAP, Teamwork, Confluence), using tools that aren’t connected will make gathering and compiling data more complicated.

5. Close

The close phase is the delivering phase of the PLC:

This step is important for teams to evaluate and document the project. The team assesses mistakes and successes that occur during the project to build stronger processes, and more successful teams for future projects.

The project manager identifies key project achievements and milestones, and documents takeaways.

In parallel, information developers complete the publish and deliver phases of the CLC:

The release report is a valuable document that gives a concrete project overview to stakeholders. It includes insights on the customer’s goals and how they were satisfied, whether deliverables met deadlines, if estimates were accurate, the KPI score, and content metrics to prove return on investment.

These phases lead to a business value alignment, when the CLC and the PLC are used together.

Connecting the CLC and PLC allow information developers to demonstrate their business value. The steps they follow to achieve business alignment can be summed up as such:

They can clearly prove their added value throughout a project and its successful completion.

This blog was originally presented as a IXIAtalks webinar with Mollye Barrett, Information Development Manager. You can find the webinar here.

Learn more about our IXIAtalks webinar series.

Blog AUTHOR

Amandine Mondélice
Marketing Coordinator at IXIASOFT

IXIAtalks panelist

Mollye Barrett
Information Development Manager

Mollye Barrett is a technical writer, consultant, and trainer. Based in Milwaukee, WI, she has over 30 years of experience working in the technical publications’ arena with hardware, software, and localization companies. Mollye specializes in XML-based authoring solutions and information architectures.


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

DITA includes the <draft-comment> element which many writers use to add comments for their Subject Matter Experts (SMEs). However, when a SME is reviewing a PDF in a PDF reader, there is no easy way to call the SMEs attention to the <draft-comment> elements. It is easy to add special formatting to make the <draft-comment> elements stand out on the page, but the SME must still page through the PDF to find them all. Wouldn’t it be handy to have a way to automatically generate a list of these <draft-comment> elements that the PDF reader can display?

Here is a fairly easy way to do just that:

Note: This process depends on an Antenna House extension – it will not work for FOP or XEP. In addition, the screen shots in this post are from Adobe Acrobat Reader 2019. Other PDF readers or other versions of Acrobat Reader might display the annotations differently.

PDF readers can already display a list of PDF annotations—the sticky notes, comments, and other items that can be added within the PDF reader when commenting on a PDF. You can leverage this capability  to create a PDF annotation for every <draft-comment> in a PDF. This annotation can be empty, since all you really want to do is provide a way for the SME to quickly view the corresponding <draft-comment>—when they click an annotation in the Comments list, they go right to the <draft-comment>.

The Antenna House documentation explains that the axf:annotation extension creates PDF annotations. It also explains the various formatting options available for the annotation. These options can be used to specify the type of annotation (which is required) but many other properties, such as border and font properties, color, the initial state (open or closed), the author, and more.

Start simply by adding a yellow sticky note annotation to each <draft-comment>.

Create the Annotations

As you might suspect, because you are adding the annotation to <draft-comment>, it is necessary to override the template that processes <draft-comment> elements in your own plugin. In the org.dita.pdf2 plugin in DITA OT versions 2.5.4 and later, this template is found in the topic.xsl file. In earlier versions of the DITA OT, it is found in the commons.xsl file.

The first line of the template looks like this:
[custom_font font_family=’Courier New’ font_size=’19’ line_height=’26’ font_style=’none’ text_align=’left’ font_weight=’300′ color=” background_color=” text_decoration=’none’ text_shadow=’no’ padding=’0px’ margin=’0px’] <xsl:template match=”*[contains(@class,’ topic/draft-comment ‘)]”> [/custom_font]

If you have not already included this template in your own plugin, go ahead and copy it in.

Next, add the following line to the xsl:stylesheet declaration of the XSL file that the template is in:

[custom_font font_family=’Courier New’ font_size=’19’ line_height=’26’ font_style=’none’ text_align=’left’ font_weight=’300′ color=” background_color=” text_decoration=’none’ text_shadow=’no’ padding=’0px’ margin=’0px’] xmlns:axf=http://www.antennahouse.com/names/XSL/Extensions [/custom_font]

This is necessary because the Antenna House annotation extensions, in this next example, include the axf:namespace, which you must declare before using.

Next, add the highlighted text to the template:

These lines create a new block and format that block as a PDF annotation. In this case, the annotation is a text annotation; it is not open initially. The annotation contains the text “Review,” has a yellow icon, and it is offset from the text by 20mm.

The result of these changes is something like this:

More importantly, the annotation is now present in the Adobe Acrobat Comments list:

SMEs can now display that list and quickly move from one <draft-comment> to the next without having to page through the PDF.

Note: PDF readers other than Adobe Acrobat might not display an annotation icon. However, the annotation is still present in the Comments list (or that reader’s equivalent) in all the common PDF readers.

Indicate the Disposition in the Annotations

The <draft-comment> element includes a disposition attribute used to indicate the status of the <draft-comment>. For example, when a <draft-comment> has been addressed, it can either be deleted, or, if you prefer to keep a record if it, have @disposition to something like “complete.” The value of @disposition can then be used to control how the annotation is created in the PDF.

To make this happen, use xsl:choose to test for the value of @disposition and format the annotation accordingly. Here, <draft-comment> elements with a disposition of “complete” produce annotations that are green and contain the text “Complete.” All other <draft-comment> elements produce annotations that are yellow and contain the text “Please review.”

In Acrobat Reader, it looks like this:

Exclude Annotations Based on the Disposition 

Alternatively, you could choose to hide annotations for <draft-comment> elements with a “complete” disposition:

Display the Assigned SME

In a case with a large PDF going out to several SMEs at once, you may want to point each to specific comments. Unfortunately, there is no SME attribute for <draft-comment> but there is an author attribute. It might not be very helpful to SMEs to know who the author of the <draft-comment> is but it is helpful to them to know which <draft-comment> elements they need to pay attention to.

Repurpose @author if you don’t need to use it to record the <draft-comment> element’s actual author. (Some might call this tag abuse, but just think of it as tag expansion.)

In any case, to do this, take the value of @author and use it as the annotation’s contents. First, create a variable that has the value of @author as its value, then specify the value of the SME variable as the value of @author:

Here is the result. BilalR can scan the Comments list and address only items assigned to him:

If you do need to use the author element for your author, or want to avoid any suggestion of tag abuse, use the <draft-comment> element’s otherprops attribute or specialize <draft-comment> to create your own element with an expanded list of attributes.

Summary

These are just a few of the things you can do with Antenna House’s annotation extensions. Experiment and see what else you can come up with!

Blog AUTHOR

Amy Kidd
Technology Manager – Technical Documentation at Emerson

Amy Kidd is an experienced technology manager at Emerson. Based in Tennessee, USA, she has a strong background in the industrial automation industry. Amy is skilled in DITA, web design, LaTeX, and software and hardware documentation. She has a BA in English with a concentration in technical communication from University of Tennessee-Knoxville, and an AA in Computer Science.


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!

Agile methodology emerged in the software development industry in the early 2000s. Many software development projects in the 1990s either failed, exceeded budget or were late. Agile methodology was a response to this trend.

Thorough analysis brought them to the conclusion that the method they used was in cause. Back then, projects were defined and planned early on. Team members agreed on their respective tasks, and went on to developing software which they only tested at the end of the project. This method left no room for adjustments or changes while the project was ongoing.

Experts thus needed to change the way software was developed into a more flexible approach that entailed increased collaboration, discussion, and feedback at the beginning and throughout the projects.

Today, agile is widely adopted in the industry. Although some software engineering departments claim to follow agile principles, many in fact only use a few of the tools it provides, leaving teammates – including technical writers – behind.

This blog will provide some tips and tricks on how to organize your work and team in the agile world, and how to avoid common pitfalls.

The Basic Principles of Agile

In 2001, the Agile Alliance was formed by partisans of a new methodology who published the Agile Manifesto which defines it.

Agile invites software development teams to focus on the people working to develop the product rather than the set-up to allow fluid workflow with discussions, reviews, and changes as needed.

Documentation must not be left out, but it needs to be relevant and written for the target audience, whether it is technical documentation or end user documentation.

Talking things over applies to teams working together, but also with customers to ensure the result fulfills requirements.

The principles listed above allow one to make adjustments when appropriate.

Here are some of the basic principles of the Agile Manifesto.

Incremental development is one of the key principles of the Agile Manifesto. The method consists of establishing top level requirements to prioritize what should be in the software.

Work is organized in sprints or iterations, meaning developments is broken down into smaller time periods over several cycles until the end of the project. Each sprint includes development, testing, reviewing, and documenting a feature.

At the end of cycles, everything that started with the iteration should be completed and ready to be delivered to customers. Progress is measured in terms of functioning software.

At the core of agile stands a cross-functional team of developers, QAs, product people, technical writers, UI and UX designers who agree on how much work they can accomplish in one sprint, and commit to finishing it by its end.

Team members should, at all times, know where other members and the overall project are standing.

Transparency gives everyone an overview of the project advancement, and makes it easier to estimate completion time. It can be achieved with tools such as ticket systems, JIRA, and digital or real-life boards with stickers.

This further emphasizes the methodology of agile where change is perceived as part of the process of continuous feedback, rather than as an error.

Agile Methodology in Practice: Scrum

Scrum is the most popular agile methodology.

The sprint starts with the product backlog. It gathers the list of top-level requirements for the user. The product owner knows what users are seeking to achieve. They prioritize user stories, assign them to teams, and determine whether a user story is accepted and completed.

An epic is a bigger user story that is broken down into smaller user stories, then assigned to development teams to be finalized in one sprint. The definition of done (DoD) is a tool that lists all activities required for each story.

At the beginning of the sprint, everyone involved –including the product owner and the scrum master— come together for planning. They decide how long the sprint will be, which is generally inferior to 4 weeks to maintain agility.

The scrum master plays an important role by supporting the team to stay in track and fulfill their goal. They ensures things go smoothly, and that acceptance criteria are met by organizing meetings(among other things).

There are regular meetings during one sprint. The daily scrum (or stand-up), which is not necessarily every day helps teams organize and debrief.

Towards the end of the sprint, the sprint review is a demo to show the result. Everyone can attend, from the people who work in the team, to other members of the company, and sometimes customers depending on the company culture.

The retrospective is a different meeting that aims at looking back and analyzing what went well and what didn’t. Actions to improve workflow are then taken.

At the end of the sprint, we get a product increment – a piece of functioning software – that can be delivered to customers.

What Challenges Do Company Face in an Agile Set-Up?

In an agile setup, technical writers can become frustrated, especially when teams fail to follow the communication and transparency principles of agile. Below are some of the most common obstacles technical writers face, and how to tackle them.

Input challenges

Oftentimes, technical writers will report that they do not receive any input from developers, which makes it hard to write documentation.

Good user stories, including the user’s wants and motivations, can help technical writers drive a topic for the documentation. As they are used to thinking like a user, technical writers can assist the product owner in writing user. Sketches and wireframes also come in handy to give a better idea of what the feature looks like.

Moreover, documentation should appear in the definition of done list. Even though tech writers can’t realistically finish writing the documentation within one sprint, with the contribution of developers to prepare it, they are better equipped to get it done in time.

Meetings are a good way to receive input. Technical writers can get information, ask questions, and provide feedback to developers. They can also schedule interviews with team members.

During sprint reviews, technical writers get a better understanding of how a feature works, especially when they don’t have access to the product. Finally, if the company hosts usability tests, they can observe new users, and improve their documentation accordingly.

Time challenges

Engineers should ideally stop coding a few days before the sprint ends for the team to stay on track. They can use this time to give input to QAs and technical writers. This makes it easier to review or redo things if errors are detected.

Technical writers who have access to the necessary specifications can start writing ahead or while implementation is being done. If this isn’t an option, using larger increments for publishing can help reduce pressure.

The longer documentation is delayed; however, the higher the risks for inaccurate or out of date information. Input from SMEs becomes hard to obtain and there is little time to finish tech writing before the product is delivered to customers –there is no time for translation either.

Working with unstructured frame makers where publishing involves many manual tasks will further delay technical writing. It is then critical to optimize your infrastructure.

Meeting challenges

Technical writers often work with many teams. As a result, they have lots of meetings to attend, in addition to their tasks aside scrum related ones.

When possible, they should limit the number of teams they’re working for or skip some daily scrum meetings. Another clue is to designate a proxy, the scrum master for instance can take notes and share all the relevant information with them later.

More importantly, each team should find out what methods works best for them.

Translation challenges

In iterative translation, modularized content must be a requirement. Tools such as IXIASOFT CCMS offer it, along with workflows for translation. In addition, the user interface must be localized before going into translation.

Other instruments to control terminology and check language are helpful to deliver quality and consistent content, which should also be a priority for translators.

Ways to overcome translation challenges include dropping the requirement to finish translations at the same time as the source material or remove translation from the agile process altogether. In all instances, translation should wait until there is enough material available. In addition to maintaining consistent and quality content, this prevents frequent changes and exorbitant translation costs.

Here are a few additional recommendations to make the best of agile methodology:

Team recommendations

In an agile set-up, technical writers should always be part of scrum teams. This will give them access to the input they need and the people they need it from. The team will also benefit from the expert feedback of technical writers and their user-centric point of view.

Infrastructure recommendations

Automated generation of output, version control and automatic builds are crucial to the system to separate the layout from the content, regardless of the tool technical writers use to write documentation.

Web-based reviews are more efficient and considerably facilitate. Markdowns are also a good idea when engineers and SMEs are involved in the process.

Working in an agile environment requires constant communication to be efficient. As they become complete members of the team, technical writers get direct access to developers and other teammates for input. Their own expertise will also benefit the team towards a successful project with fewer frustrations involved along the way!

This blog was originally presented as a IXIAtalks webinar by Marion Knebel from parsonYou can find the webinar here.

Learn more about our IXIAtalks webinar series.

Blog AUTHOR

Amandine Mondélice
Marketing Coordinator at IXIASOFT

ixiatalks panelist

Marion Knebel
Senior Technical Communicator at parson

Marion Knebel is based in Berlin, Germany, where she works as technical writer, consultant, and trainer at parson. She specializes in XML-based authoring solutions and information architectures. Marion is a certified Scrum Master. Her training in agile allows her to collaborate efficiently with companies working with this methodology.


Sign up to our newsletter now to keep up with the techcomm industry and IXIASOFT’s latest updates!