CIDM Matters

Sabine Ocker, Comtech Services
January 15, 2020

Since at least the end of 2017, we have been hearing that the chatbot revolution is coming. But there have been only rumors and hints of upcoming implementations. We hear of some chatbots being implemented, but almost exclusively in the marketing content domains with limited applicability to customer support or technical product documentation. Apologies to T.S. Eliot, but the chatbot bang has not happened.

Last month at the CIDM Round Table, we asked members to talk to us about their chatbot implementations. We had an excellent turnout and an interesting discussion, but as it turns out, no member organization in the conversation has a chatbot; they all came to learn about someone else’s. As one member said, “…in DITA you have the semantic structure and the intelligence already,” so if you have metadata and the ability to scope to the right granularity of content, such as just a procedure, then your chatbot will be in a better position to deliver a precise answer. The operative part of this statement seems to be the word “if.”

I started thinking about why this is the case. Given the leg up which DITA gives organizations to provide an environment to mine their semantic-task-based-action-oriented content for answers to help their users, why aren’t we in the chatbot revolution?

There may be many reasons, but I identified at least two.

The first is because of content silos. There is no such thing as a product documentation chatbot, a marketing chatbot, or a support chatbot. There is just a corporate chatbot. So, if there is only a company chatbot, then the effort to develop it, implement it, populate it with content, and ultimately fine-tune it must be an Enterprise-wide effort. Furthermore, any chatbot must engage with users before, during, and after they have made a purchase of a product.

Similar to other enterprise endeavors such as taxonomy, creating a chatbot requires involvement, input, and ownership from key stakeholders from all content domains which represent any stage of the user journey. Of course, user journeys vary from company to company and can encompass many more stages than those listed below, but most have a variation of at least these four:

1. Discovery
2. Evaluation and selection
3. Delivery/Installation
4. Ongoing Usage

The content which users may need to answer their questions in each stage:

1. Product briefs, customer reviews, or product documentation
2. Product specifications, sales brochures, product catalog, product documentation
3. Product Documentation, Training courses, and content
4. Knowledge Base articles, product release notes, support, and troubleshooting content

This means the enterprise chatbot will need content inputs from the Marketing, Technical Product Documentation, Customer Support, Sales, and Learning and Training content domains at the very least to be effective across the entire customer journey.

A complex enterprise chatbot ecosystem of content sourced by, owned by, and updated by these different organizations is challenging to implement and maintain, especially if that ecosystem has a built-in requirement of constant tweaking and fine-tuning based on feedback on how users are engaging with […]

Shwetha Madhan, VMware
January 15, 2020

As an information developer at VMware, I write all kinds of technical documentation – including the Workspace ONE UEM release notes. To create these release notes, I pull together new feature blurbs crafted by other writers and consolidate all of them into a new document. When I took over this task a few releases ago, I observed a common pattern. All the “What’s New” blurbs had a classic stand-up language: “Added support for XYZ”, “Added X and Y field under Z”, and so on. I wondered — why? Why is the text treating me like a robot? Do real people talk like this? During a stand-up, it’s normal to talk directly about the code that is written, but that information isn’t particularly useful for the end-user. Stand-up verbiage only results in opaque, impenetrable content.

I get paid for the text I write. But I often wonder if customers read and like what I write. Creating content that resonates with our readers is an often-overlooked part of our job. It’s one of those niche skills that not many talk about it. But it’s incredibly important and it can be difficult to do. Besides, release notes are one of the user touchpoints that most of us ignore or pay less attention to. Mostly release notes are treated as an afterthought or even a chore that most of us put off until the last minute. But in a SaaS-paced world, release notes represent a key point of engagement with customers. It is one of the pivotal pieces of documentation that tells our current users why the new release is important to them and at the same showcase our product to the potential users. While it might sound straightforward, writing release notes is an important task that requires more skill, care, time, and attention than it is given.

As a release notes wrangler, my first stop in researching the art of writing great product release notes was, of course, Google. I found encouraging rumblings in the industry about making release notes more engaging, and information about the great benefits to doing so. Several other companies are starting to value and understand the importance of release notes and use them as an opportunity to communicate with the customer base. Slack, for example, thinks release notes are an excellent opportunity to create engaging content that deepens the relationship with their customers and make them easy to understand.

As I started to take up this task more seriously, I recognized a strong need to make our release notes more useful than the default. When I began to postmortem our “What’s New” section, I felt like I was reading an elevator pitch by a robot. The content was boring and too technical, and it deserved an upgrade. As a data-driven writer, I asked myself a key question: Do people even read our release notes? I was surprised to learn that even though release notes are just one percent of […]

Suyog Ketkar, Autodesk
December 1, 2019

If it is true that our work defines us, then technical communicators and jugglers are alike. Just that we play toss-and-catch between project deadlines, tools, requirements, meetings, and even products. Writing is only an aftereffect of our juggling. Which is why problem-solving may take backstage. We don’t always essay to address what the seekers require, but what our design and development teams have to offer. Through this article, I put forth the questions that came up in a recent coffee-table interaction on how we could fill this gap. […]

Sabine Ocker, Comtech Services
December 1, 2019

Moving to DITA from an unstructured publishing environment is no small feat.  The project has many workstreams and the average migration and implementation project can take up to two years. The main aspect of any migration project is the conversion of existing content into DITA XML files. […]

Stanley Doherty, Ph.D., Oracle Corporation & OASIS DITA Adoption Technical Committee
November 15, 2019

As change initiatives go, DITA is often described as being “highly beneficial and highly disruptive” for the organizations adopting it or making ongoing investments in it. As anyone who has been involved with a DITA migration or upgrade will attest, the “disruptions” always precede the “benefits”. Although a risk analysis should be at the heart of every DITA migration or upgrade initiative, we do not have a shared vocabulary for assessing it. […]

Desiree Livermon, Genesys
November 15, 2019

What do you think of when you hear the word “accessibility”? For many people, it evokes images of wheelchair ramps, automatic doors, and maybe some braille in the elevator. For content developers, it mostly makes us think of screen readers. But there is more to accessibility than a robotic voice parroting the words you have written. […]

Jane Wilson, VMware
November 1, 2019

It’s always frustrating to hear about our deliverables, “The documentation is bad.” Beyond the fact that it’s negative, that simple statement is not actionable. There are no specifics about what part of the documentation is “bad,” much less what’s wrong with it or what “bad” means. Follow-up questions might lead to a little more detail: “I just hear it’s bad,” or “A customer told me it’s bad.” Obviously, this is not helpful in trying to address, much less fix, the problem. […]

Theodore Wolff, Danfoss
October 15, 2019

A few weeks ago, I spent three increasingly frustrating hours assembling a new TV stand with one of those fancy mounting stands on the back of it. I started the evening full of hope that I would soon have a new, safer way to display our TV and reduce the danger to our two-year-old son. Best of all, the conditions were perfect. Our son was away that evening, as well as our two dogs. […]

Mary Dickens, Cengage
October 1, 2019

Technical communicators are often called upon to support multiple development teams; it’s rare for every team to have a dedicated Technical Communicator (TC). To deal with this, writers on a high-functioning TC team need to be able to take on stories for sometimes unfamiliar products and technologies, avoiding silos of expertise in favor of flexibility. Inadequate user story writing leads to confusion and delays work completion. […]

Kathy Madison, Comtech Services
October 1, 2019

All things associated with measurement was the theme of this year’s Best Practices conference last month in Austin, Texas.  Doug Hubbard, the keynote, kicked off the conference by challenging us to rethink our perceptions of the concept of measurement, the object of measurement and the method of measurement.  He started by defining measurement as an expressed reduction in uncertainty based on observation. […]