Let’s Break a Tech Comm Rule

Update: Links to all session slides and recordings are grouped here.

I’ve been a technical communicator for nigh on 20 years. I teach technical communications. I theorize about technical communications. And for all this time, I have steadfastly held to the great rule that you do not mix concepts with tasks.

DITA has three major topic types. Two of them are Concept and Task. Why? To keep them separate, of course – everyone knows that!

And yet – and yet – and yet – here I am, telling you that “everything we know is wrong.” Continue reading “Let’s Break a Tech Comm Rule”

The Humanist Nerd Reviews Adobe TC Suite 4

Adobe recently released Technical Communication Suite 4 (TCS4), the latest version of their integrated collection of technical communications tools.

Context

I am a long-time FrameMaker and RoboHelp user – I used RoboHelp when it was still an independent company called eHelp, and have seen it evolve through several acquisitions, several versions, often retaining some of its most frustrating problems, even after transitioning from eHelp to Macromedia to Adobe.

I stopped using these tools, not because I didn’t like them any more, but because their model no longer conformed to what I needed: structured, modular XML authoring with multiple publishing channels.

This also means that I am no longer the expert I once was on these products, and have have tested some of what is available in TCS4, without (yet) drilling down into its depths. Continue reading “The Humanist Nerd Reviews Adobe TC Suite 4”

Reflections on CMS/DITA Europe

OK, I asked for it. I posted, in a public forum, that the price of attending the CMS/DITA Europe conference was too high for a lone consultant such as myself. The folks at CIDM, who organize the conference, told me to put my money where my mouth is, and graciously offered me a one-time discount that made it possible for me to attend – for which, many thanks.

I am not totally comfortable about receiving a privilege that might not be available to some people less in the public eye, and I seriously debated whether to accept or not. After consulting with some colleagues whose opinions I respect, I finally decided that yes, I would attend, but would also share my experience of the event here in this blog, honestly and publicly, regardless of which way it went. Continue reading “Reflections on CMS/DITA Europe”

Doing Well by Doing Good

In the late 1930’s, two significant political figures discovered new technology.

At the time, the new technology was called Radio. And both of these political figures discovered, pretty much in parallel, its power and influence.

One of these figures was Nazi Propaganda Minister Joseph Goebbels.
The other was New York City Mayor Fiorello La Guardia. Continue reading “Doing Well by Doing Good”

Why Isn’t It?

In 2009, I delivered a short, light-hearted keynote address to the STC France annual conference, entitled, It’s Not in the Job Description. This post answers that presentation with a question: Why isn’t it there? What is it that we really do, anyway?

Defining Our Profession

I’m indebted to Mark Baker for his post, The Web Does Minimalism, which I recommend to everyone, and for his response to my election post on STC’s business model. His remarks crystalized for me a number of things I’ve been reflecting about over the last few years.

We used to have a pretty straightforward idea of what we did. We were technical writers, and we wrote manuals. We provided the bridge between engineers and their world, and users. We were able to translate from the functionality-based thinking of a product’s creators, to the task-based mindset of the end users.

We were also at the end of the food chain. We had to wait until the product was done, then chase engineers around with our notepads to try and get an idea of how something was supposed to work (not necessarily how it actually did). And we always got blamed for release delays.

Today we do many things that have never been thought of in the context of technical “writing:”

  • Interface design – user assistance is embedded in the interface. How can we design it if we don’t get involved with interface design?
  • Software information content – software today is an information rich environment, and often has to talk to users in one or more clearly defined voices. We write a lot of this content, whether or not it concerns user guidance.
  • Content strategy – this is a new buzzword, more or less since 2009, but if anyone thinks we didn’t do this before, they’re nuts. We’ve always had to make our work fit into an existing strategy, when there was one, and we’ve often helped define one when there wasn’t – it just wasn’t formalized. Now it’s getting more so.
  • Information Architecture – most of us don’t like being told we’ve got to fill in all the lorum ipsum’s that some designer has created for us without ever asking us what we needed to write and what prominence it needed. But we also can’t really start writing if we don’t have an idea of the structure it’s going into. In truth, content and structure need to evolve together and in parallel. So we do a bit of IA as well, and work with designers and information architects to make sure our content has a place to go – the right place to go.
  • Localization – Most of us don’t do translation, even if we are able to. But localization is not just translation. All the activities above also need to take localization into account. You need a good 30% more screen space for material in French or German than you do in English, just take a mundane example. Then there is the HOW you write – there are ways to write that make translation easier – and less costly, too. We have to know about them. Fortunately, most of these techniques also make better source language content.

I’m sure we could find a few more, but you get the idea. The fact that we do all of the above does not necessarily make us experts in all the fields mentioned. We are technical communicators: jacks of all trades, masters of some. We work in teams with other content workers, engineers and developers, marketers and designers, to create content in a variety of environments and situations.

Our skill, today, is not knowledge of English grammar or good style – though these are tools we must have in our kits. It’s not our knowledge or this or that desktop publishing solution, DITA schemas, or CMS systems, though these are also important.

Our primary and most important skill in today’s market is the ability to find information quickly, synthesize it, and make connections where relationships don’t seem apparent.

To quote Mark Baker, knowledge is no longer a salable commodity. Instead, it is “the calling card of expertise.”

In this context, all the definitions of our profession in all the labour bureaus throughout the world are obsolete and out of date.

Find Your User’s Voice

I’m working on an interesting problem these days. I have a client who is about to release a new software product. I can’t tell you what it does, for obvious reasons, but I can tell you that it does some neat things. Perhaps too many.

It provides users with all kinds of useful information. Some of it is useful for a group of users – call them Group A. Some of it is useful for another Group B.  They aren’t interested in the same things, and for some information,  Group B wants to know about it, but Group A not only isn’t interested, they’re not authorized to see it.

Access to sensitive information can obviously be solved with user profiles, but it’s a challenge to sell the same software to two different audiences. To facilitate the task, we’ve decided to create two different interfaces, one for each of the groups. When a user logs into the software the interface s/he sees is dependent on a user profile associated with the login. The other interface is not available.

That was the easy part. Next, we have to design the interfaces. And each interface has to communicate with its user group in language that makes them comfortable, and, above all, inspires confidence in the software.

It’s early days, but here are a few guidelines I’m working on that you might also find useful:

  • The design (look and feel, user interaction model) of the two interfaces needs to be sufficiently similar that should someone need to have access to both, they don’t need to relearn everything to use it.
  • At the same time, the same elements of the interface need to be fine tuned to appeal to very different user populations – for example, one might be technical, or engineering oriented, the other might be business oriented. One might be implicated in operations, the other might be financial, etc.
  • The language, labels, messages used in each interface need to be 100% adapted to the user group’s profile.
  • When writing the messages and content delivered by the software, we need to think about subtext as well as overt meaning. When two people have a conversation, there is enormous subtext based on power relationships, expectations, tone of voice, etc. When software provides information to a user, there is an implied notion that one or the other is the expert. How the software communicates with the user needs to be aligned with whether the software or the user is expected to be the expert, and the tone of the communication needs to be equally adjusted.
  • The user guidance, also needs to respect the target audience. This is harder the it might seem. Some of the user guidance is common to both interfaces – and needs to maintain that level of confidence for both, despite the fact that the two groups tend to favor very different communication styles.

My takeaway from this exercise so far: when we talk about content strategy for software, we really need to take a holistic approach, and realize that content and style need to be coherent, and in resonance with the nature of the information itself, and the user who must interact with it. Interactivity, in this sense, needs to take certain aspects of human communication into account if it is to succeed at convincing users and gaining their trust.

Where Would You Take This Idea?

I invite your comments, thoughts or reflections.

I’m on The Mindtouch Top 400 List

Mindtouch has included my two Twitter personas, @raygallon (number 118) and @gallon4stc  (number 259) on its annual list of top influencers in technical communication and content strategy.

I am really delighted to be included, but share some questions about the methodology with David Farbey. Rather than repeat all his arguments, I’ll direct you to his blog post on the subject. 

In my case, @gallon4stc is a persona that was created exclusively to run my campaign for office in STC, and keep that separated from my main tweet stream. It has relatively few followers and a small number of tweets. If the algorithm is purely quantitative, I don’t know how I made it to the list. If there are qualitative criteria (one might be, for example, the influence of a persona’s followers), I’d like to know more about how they were constructed.

So thanks, Mindtouch, for the honour, and please help us understand better how we got there!