Punched by Minimalism

Originally published in the March 2014 of Intercom, STC’s monthly magazine (http://intercom.stc.org/).

I am always reticent to share my off-hours activities with my colleagues and professional acquaintances. It is nothing illegal or shameful, mind you; but, simply the memory of the look of confusion and misunderstanding I have gotten at times is deterrent enough.

What do I do once I shed my technical writer’s suit? I get punched, I get kicked, I get chocked, I get threatened by a wide range of weapons, and I fight back.

I am a level 5 Krav Maga practitioner. Krav Maga is a violent and dirty-fighting, hand-combat self-defense system—if you have never heard of Krav Maga, think Liam Neeson in Taken. Its violent efficiency has made it the combat system of choice for a multitude of law enforcement agencies and Special Forces units worldwide (Israeli Defense Forces, FBI, LAPD…). In the US, civilians can learn to defend against a variety of real-life, unarmed and armed attacks through a 5-level curriculum starting at level 1.


So what does it have to do with technical writing, you might ask? That was also the question I was pondering when thinking about this very same column. And then, I had my Eureka moment: Krav Maga is to martial arts what minimalism is to writing!

Both minimalism and Krav Maga are driven by principles. Pr. Hans van der Meij defines the minimalism principles as follow (http://users.edte.utwente.nl/meij/minimalism.htm):

  • Choose an action-oriented approach
  • Anchor the tool in the task domain
  • Support error recognition and recovery
  • Support readers to do, study, and locate

Let’s see how Krav Maga fares against these governing principles.

Choose an action-oriented approach. Minimalism principles dictate addressing real tasks that users want to perform and providing an immediate opportunity to act, whereas Krav Maga advocates counter-attacking immediately after the initial threat has been addressed, or simultaneously, if possible. These two principles sound rather similar in empowering users/practitioners to act immediately with no delay — all in the name of efficiency.

Anchor the tool in the task domain. One of the tenets of minimalism is to focus on achieving real goals and completing real work rather than describing the features. In other words, we need to provide users with the instructions that are necessary to perform a task, nothing less, nothing more, in words to which users can relate in their work environment. In Krav Maga, there are no somersaults or beautifully elaborate techniques practical only in the confines of a dojo, only simple techniques that works in the streets, where they’re supposed to be the most useful. Our most reliable, most used, and most loved weapon is a kick to the groin, beautiful in its simplicity and efficacy. Krav Maga and minimalism strip down hand-to-hand combat and writing, respectively, to the bare minimum to ensure maximum efficiency.

Support error recognition and recovery. Minimalistic writing must provide error information that supports detection, diagnosis, and recovery. When dealing with self-defense situations, errors might have dramatic, if not fatal, effects. Krav Maga preaches to always train from a situation of disadvantage and encourages committing errors in the safety of the training room where they can be corrected. This method of training ensures that if a mistake or an unexpected event happens in the heat of the moment, the practitioner is not flustered and confused but can successfully recover from it.

Support readers to do, study, and locate. Minimalism is about providing the right information at the right time. For Krav Maga, providing the right information at the right time means delivering techniques that address actual and current threats. Krav Maga is an open system; techniques that are not relevant anymore are made obsolete to leave room for techniques that address threats that are becoming more common.

Now I have my answer when a colleague asks me what I do after work: “Same think as I do at work, I apply minimalism.”

Keep calm and let the tech writer handle it.

Doing some research yesterday, I ended up on the website of the maker of a very popular, trendy, and sleek-looking camera. Of course, I felt compelled to have a look at the documentation. Giddy with anticipation, I clicked to open the PDF, expecting a user manual as groundbreaking as the product. The layout was very sleek, very modern, and on par with the product. However, to my immense surprise, the content was not on par with what is now considered modern technical communication standards and best practices. Not that the instructions were bad, incomplete, or poorly written, they were simply not rooted in the task domain, but very much object-centered. For example, this camera has a feature called One Button that allows recording to begin as soon as the camera is turned on, without the need for any other manipulation – a pretty neat feature, if you ask me. Unfortunately, the procedure to activate this feature is buried in the Set Up chapter, under a One Button heading and a task titled To turn the One Button mode ON, the purpose of activating this feature being briefly mentioned in the introductory paragraph.

This structure describes a feature of the product, not an action that a user might want to perform: I don’t think of one single reason for which I’d like to turn the One Button mode ON for the sake of it, but I can definitely see why I would want to start recording as soon as I turn my camera on.

Thinking along these lines, we can easily go from To turn the One Button mode ON to Start recording when powering the camera on, from object-centered to user-centered, from features to users’ scenarios.

Do get me wrong, my goal is not to point the finger at this company or to make fun of their documentation. Although I don’t have one of their products, I have seen them in action and I think they’re great cameras. I am simply using their user guides as an example of what I have seen quite frequently, notably from technology companies.

In today’s world, startups and Agile environments become more and more preponderant and organizations, for the sake of staying lean and mean, often ascribe technical documentation duties to their development teams. And development teams are, well, development teams. They see a product as a sum of features replying to a list of requirements, as they should, and they describe these features in the documentation.

Writing is just writing, and everybody is a writer, right? Well, there is a method to the apparent madness that technical writing is. We call ourselves the first users, the users’ advocates, and other user-centered sobriquets for a reason: we translate features and requirements in the light of audience and task analyses into users’ scenarios to eventually create procedures that use our products’ features to fulfill our users’ goals.

Trust us, it’s what we do.

DITA and the table conundrum

I am a big fan of DITA. I like the structure that the DITA framework provides, and I like the scrutiny it implies to apply the proper semantic tags or concept types.
I am a big fan of tables. I like the structure tables provide to organize content, and I like the clarity they give to complex information.
And yet, I am torn when using tables in DITA!
OASIS DITA Technical Committee defines the table element as arbitrarily organizing complex relationships of tabular information, which sounds about right.
As I construe the general concept, a table is a formatting tool that allows communicating complex and intricate dataset in a way that is easier to digest and comprehend for the audience. And I use this tool quite often, formatting paragraphs of text in easy-to-read eye-pleasing tables.
Let’s read back a bit: arbitrarily, tabular information, formatting tool, eye-pleasing…so many terms that are oh-so un-DITA! One of the core principles of DITA is the disconnection of content and format: semantic tags act as containers for content and publishing platforms interpret these tags and apply formatting according to style sheets. And yet, we have here a DITA element that both tags “semantically” content and forces formatting towards a predefined structure.
I appreciate that nothing prevents using table and applying a formatting style that totally departs from a traditional tabular format, but why would one do that?
First, I think it would be quite facetious to use an element named “table” and not make a table out it, and secondly, the hierarchal structure of the table element with child (tgroup), grandchildren (thead and tbody), great-grandchild (row), and great-great grandchild (entry) would make developing the style sheet quite interesting if it was only to apply a bold typeface.
On the other hand, the table element does not really contain content; it is a container for other containers. The element that contains content in a DITA table is entry. What is semantically an entry element?
I can imagine from a semantics’ perspective the type of content that title, p, cmd, or step must contain, but an entry element? According to the OASIS DITA Technical Committee, the entry element defines a single cell in a table, which brings us back to format and semantics wrapped tightly in the same element.
However, structurally, an entry element can contain a slew of true semantic tags and that, maybe, contains–no pun intended–the solution of my dilemma: let’s apply semantic tagging at the entry level and use table for what it is, a bucket that we can fill with complex information we want to logically organize.

Technical content is an asset – Part II

The first part of this entry was about technical content as pre-sale assets. The opposing, or complementing, I should say, view is easier to defend: with trepidations of excitement, the customer tears open the packaging of the just-bought brand-new product, and lo and behold, here is the user guide in all its glory.

Instructions instruct and help systems provide help, nothing more, right?
To a certain extent, yes, these are the primary functions of technical documentation, their raison d’être, and, let’s face it, the reasons of our survival in certain organizations.

But, they can be so much more, especially in this age of Yelp and customer reviews: a customer, confused by the matchstick instructions, cannot put his Billy bookcase together and it is all over the web! The post won’t certainly read “IKEA tech writer dropped the ball on this document” but more likely “IKEA bookcase is difficult to assemble”, or something even less savory.

On the other end of spectrum, a MacBook Air user who browses online merely half an hour after opening the box might rave about how Apple products are great and easy to use, without noting the user assistance seamlessly embedded in the user interface that guided him all the way to cyberspace heaven.

Good technical content makes the products easier to use for the customers, and happy and satisfied customers become, in turn, brand evangelists. Good content participates in building the brand’s good reputation.

Technical content is an asset – Part I

In this age of keyword optimization, “likes”, and retweets, there is no denying that content is taking front and center in building value. Content generates traffic, then turns traffic into leads, and leads into sales.

A traditional view is that marketing content is pre-sales whereas technical content is post-sales. Potential customers need to know all the wondrous features of a product to decide whether to purchase it or not but only need documentation once the product is in their hands and they become users.

Does the paradigm still hold true?

In the olden days, customers only had one way to get their hands on the documentation: they had to buy the product. Nowadays, they can download a user guide to their device of choice with only a few keystrokes, mouse clicks, or finger gestures, whether they purchase the associated product or not. I know I do. As a customer, if I need information on features, requirements, ease of use before buying, I always go to the documentation. Sure the marketing piece is informative, but for the nitty-gritty or to ensure that a feature works as advertised, nothing beats the documentation.

I can’t dismiss that professional curiosity might play a part, but I was doing it even during my days in the lab. My labmates and I always took marketing collaterals with a grain of salt: “Of course they say that we can do A, B, and C, they want us to buy their product! Let’s check the manual.

Very few things are more frustrating than realizing upon receipt of a product that an ancillary reagent or piece of equipment, yet indispensible, is unavailable. Checking the documentation for a “materials required but not supplied” section before ordering can avoid this aggravation.

Not only can documentation be used to assess how easy to use a product is (how long and involved the procedure is, for example), but also to estimate how robust a product can be. Somehow, a one-page procedure followed by 20 pages of troubleshooting does not reflect sharp product design.

In conclusion, when there is no doubt that documentation is an important part of the user experience, it is now more than ever clear that technical content adds value to a product and to a brand by acting as an ambassador to their customers.

Under the gun

The islands of Loreto

The islands of Loreto

The beautiful islands of Loreto where I am spending a well-deserved (by my own judgement) family vacation serve as backdrop of today’s entry.
Benjamin Franklin said there were only two things certain in life: death and taxes. But after last week spent “under the gun” of a barrage of deadlines as my absence was looming at the horizon, I’d like to add a third thing to the list, with technical communicators in mind: deadlines. “I’ll get to that tomorrow/next week/next month, I am under deadline” must be one of the most used sentences in the world of technical communications.
As I was reflecting on how small a technical communicator can be when facing deadlines, I was reminded that soft skills are as important as technical skills. Working under deadline and a mounting pressure is, of course, a given but let’s not forget managing expectations in terms of time and delivery.
We are so many times asked to deliver on short turnaround (how long can it take to make a rough draft look pretty after all?) but I do think that it is our responsibility as “first users” to take the time to iron out all the kinks and make sure that we produce the best user’s experience possible. Good documentation takes time and shortcuts are not always the best path to a successful project.

The first step is always the hardest

Well, here it is: my first blog post ever! It only took me 20 years or so to strike the first keys. Usually early adopter to the core and to a fault–I still remember rushing to the store to get my HD-DVD player, I’ll blame two culprits to my tardiness to the blogging train: my inherent introversion that makes the idea of exposing publicly my signed words as comfortable as that of repeatedly hitting my right thumb with a hammer and my previous life as a bench scientist.

Scientific research can, at times, make “Games of Thrones” look tame: students compete for fellowships and mentors; scientists compete for grants, positions, and publications. One would assume, with reasons, that trying to survive in the scientific equivalent of Westeros is not the most auspicious to sharing information, let alone blogging. Everyone is out to steal the beloved data you gathered at the sweat of your brow, so why would you share it freely online for the world to see? Needless to say that my foray in research did wonders for my budding paranoia.

So, what changed?

Last week, I was a first-time attendee to the 61st Society for Technical Communication Summit (#stc14) in Phoenix, Arizona and what I saw left me dumbfounded: professional technical communicators sharing slide decks, tweeting, and blogging, in one word, collaborating.

Even relatively new to the profession, I am too a realist, some might even say cynical, to think that, Tech Comm is a perfect world but emerging myself in this new culture was refreshing and definitely gave me a new outlook on social online presence.

So here I am, blogosphere, adding my own two cents and hopefully, contributing to the greater good.