Delighting users by killing XML robots


The Force Awakens! Or in this case, my ongoing battle with DITA-XML awakens! In the 1st and 2nd episodes of my controversial “Killing XML” trilogy, I explored the rising external forces of social media and mobile apps. But in this 3rd episode, with the rise of socio-mobile, I’ll explore the rising internal forces of human voice and user delight, which are often choked by content cost and maintenance.

Recently, while catching up on old PDF issues of Intercom, the monthly magazine by STC, I found a February 2015 article that advocates this “delightful” approach for technical docs. In his article, Barry Grenon observes that technical writers “default to a formal style” that sounds robotic and encourages “remaining invisible”. By focusing on cost and maintenance, writers fail to engage or delight users.

STC Intercom: February 2015

STC Intercom: February 2015

Hi, my name is Jay, and I’m an IBM TRIRIGA information developer at IBM. Let me ask you this. If you’re anything like me, a seasoned technical writer with years of DITA-XML experience, how do you know if you’ve forgotten to “delight users”? Well, it’s easier to see it if you’re also a blogger. But if you’re not, do you notice yourself stripping away your unique voice or personality from your content?

What do I mean by “your unique voice or personality”?

First, here’s a little background. In 2011, when TRIRIGA was acquired by IBM, our small TRIRIGA information development (ID) team began the painful process of “blue-rinsing” our Microsoft Word user guides to resemble the IBM ID look. In 2012, we began the slower process of “blue-washing” and converting them from DOC to DITA-XML. To speed things, I trained to be a DITA-XML code reviewer.

Looking back, the process of “blue-washing”, writing, training, and reviewing in DITA-XML — which conditioned me to “think more, write less” and adopt a minimal, translatable, reusable ID style — also “brainwashed” me to strip away my unique voice or personality from my content without much effort. But that’s the goal, and that’s the point. So the question is: Did I notice it, realize it, or care about it?

My answer is: Yes, by the end of 2013, I finally began to realize it — my lack of satisfaction and delight with our DITA-XML docs. Which gave birth to my first “Killing XML” blog post: “Killing XML and IA with social media“. So let me ask again: Do you notice, realize, or care when your perfectly mass-produced content sounds inhuman or robotic? But this question is probably related to: Do you have a choice?

What happens if you do “have a choice” to delight users?

I was lucky. While we didn’t “have a choice” from 2011 to 2014, I learned so much from my DITA-XML experience. I still appreciate that. But I was also lucky because my longtime extracurricular blogging kept my creative voice alive and kicking during this period. Without this blogging “shield” to protect me, I might not have realized this “brainwashed” loss of delight. Or I might’ve forgotten or ignored it.

Then something happened. In 2015, I was given the golden opportunity to create a brand new vision of documentation to introduce our brand new TRIRIGA UX Framework. In my previous post, I wrote:

How do we get customers to be excited about a new framework? From my high-level discussions with development managers, they wanted the docs to be “cool”, “exciting”, “consumable”, and “accessible”. So based on their words, I formulated a new vision of “cool, casual, and consumable” articles, written in the same conversational and colorful way as I’d write one of my own blog posts.

Thus, the TRIRIGA UX Articles were born! In terms of “cool”, I ignored the old-school Knowledge Center and borrowed the big bold visual impact of WordPress blog posts. In terms of “casual”, I sprinkled some rhetorical questions, metaphors, slang, and humor. In terms of “consumable”, I split the mobile-friendly PDF content into more-digestible chunks for slightly-different audiences.

But by ignoring the Knowledge Center, did I ignore its DITA-XML too? Yes, definitely. Then what did I use? Naturally, I chose Microsoft Word DOC. Why not? Ever since my mobile PDF experiments from 2 years ago, it was the simplest choice for mobile-friendly PDFs. In fact, being away from DITA-XML for 12 full months was an eye-opening and liberating experience. Like my human voice was finally freed!

TRIRIGA UX Article 1

TRIRIGA UX Article 1

In other words, I went back to the basics. I chose the simplest most-convenient writing tool to design the most-visual and most-engaging reader experience. So without realizing it, I was following Barry Grenon’s “delightful” approach for almost a year before I found his February article “Writer’s Block”. My casual style also echoed Barry’s example: “Now be careful with this next part, it gets really tricky.”

If I understand him correctly, Barry hopes that we as technical writers can unshackle ourselves from the robotic constraints of DITA-XML mechanics, internationalization, and other secondary cost and maintenance issues, and return our primary focus to writing and showing pictures as naturally and humanly as speaking to our next-door neighbors. After all, how do we put a price tag on delight?

Meanwhile, feel free to peruse Barry Grenon’s article “Writer’s Block”, first published in the February 2015 issue of Intercom. For convenience, I also highlighted the lines that struck me the most. Enjoy!

STC Intercom: February 2015

STC Intercom: February 2015

STC Intercom: February 2015

STC Intercom: February 2015

STC Intercom: February 2015

STC Intercom: February 2015

STC Intercom: February 2015

STC Intercom: February 2015

STC Intercom: Writer's Block

STC Intercom: Writer’s Block

STC Intercom: Writer's Block

STC Intercom: Writer’s Block

STC Intercom: Writer's Block

STC Intercom: Writer’s Block

STC Intercom: Writer's Block

STC Intercom: Writer’s Block

What are my final thoughts?

You can’t delight everyone. If creators of movies, novels, and games simply “played it safe” and tried to satisfy every culture, religion, and language with the lowest common denominator and without any unique adjustments for each group, they’d probably anger, annoy, or bore everyone. Doesn’t this also apply to authors of technical docs? To delight our readers, we must decide where we can be natural.

We must also be aware that our audiences are evolving as well. In the September 2015 issue of Intercom, I was struck by an article that explores the technological expectations of the “Millennial” generation. In her article, Victoria Deen McCrady finds that Millennials “make decisions based on convenience” and are “defined by impatience”. Aren’t our audiences becoming more Millennial too?

Consider these findings from her article: (1) “[The Millennial] group freezes when they encounter text-heavy instructions or advanced options (radio buttons and dialog boxes).” (2) “Programs that look like social networking sites, with sleek design, obvious graphics and areas to click, make [Millennials] feel comfortable.” So as technical writers, we must embrace delightful content today more than ever.

Like before, feel free to peruse Victoria’s article “Millennials”, first published in the September 2015 issue of Intercom. For convenience, I also highlighted the lines that caught my eye the most. Enjoy!

STC Intercom: September 2015

STC Intercom: September 2015

STC Intercom: September 2015

STC Intercom: September 2015

STC Intercom: September 2015

STC Intercom: September 2015

STC Intercom: September 2015

STC Intercom: September 2015

STC Intercom: Millennials

STC Intercom: Millennials

STC Intercom: Millennials

STC Intercom: Millennials

STC Intercom: Millennials

STC Intercom: Millennials

Related articles

3 thoughts on “Delighting users by killing XML robots

  1. Pingback: Rewriting the rules for TRIRIGA docs | jay.manaloto.ibm

  2. Pingback: Killing XML and IA with social media | jay.manaloto.ibm

  3. Pingback: How do you write content that delights users? | STC Southern Nevada

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s