I have had one technical writing job where I actually communicated with my user in a meaningful way, on a regular basis. In that position, I was both the technical writer and the trainer. I worked closely with the one support person on my team. I even covered the phones and answered support e-mails. We had a small user base, so it was possible and necessary for me to work directly with our users.

Since then, I have worked on products with much larger user bases and therefore, much larger organizational structures to support those user bases. I find myself writing documentation for users I never actually talk to. In fact, my contact with users has mostly been limited to meetings held for the sake of design and development, where the conversation is about how users “might” use the future product. Support and training are completely separate from documentation, and as far as I can tell, they rely on their own, home-grown documentation. So, there is essentially no way for me to know whether the documentation I write is meeting user needs.

The user has stopped being my main audience. I write to satisfy subject-matter experts (SMEs), my boss, and sometimes my peers. I do my best to think from the user’s perspective - I try to do right by them. But, the user is often a made-up person whose habits and expectations are eerily similar to my own. How can I write to satisfy the real, but very silent user?

I’m not saying that the way things work is a bad thing. I am saying that I don’t understand it. It seems counter-intuitive, but I can’t help wondering whether I’m thinking about it all wrong.

I’m a cog in a very large machine. I don’t understand how the machine works. I really don’t understand why it works the way it does. Given that I do not talk to the user, am I supposed to serve the user by serving the machine? Is it enough to satisfy the SMEs, my boss, and my peers, while hoping for the best with the actual user? And, if not, what should I do?

This blog, like zombies, has risen again and is out to eat BrAiNSsss!!!! Or, at least the quality of this post will made you feel brainless if you trudge through to the bitter end. So, let’s get started.

I recently read this incredibly awesome post on I’d Rather Be Writing - If No One Reads the Manual, That’s Okay. The ensuing discussion in the comments was just wonderful. And, it made me realize that Stephen King really had this whole reading the manual issue figured out.

You see, there is a time when people will be overjoyed to have user guides and manuals. They will pour over the carefully written tasks with avid attention and make notes in the margins. It will be a technical writer’s paradise. Word-nerd Nirvana!

That time is the Apocalypse.

Imagine the benefit of manuals when 99% of the world’s population keels over. Sure, there will be a period of mourning, a time when survivors will think of nothing except their sorrow, their loneliness, and their next meal. But, eventually, according to dozens of credible post-apocalyptic movies, they will realize that it’s their responsibility to rebuild the human race. And, trust me, when they start getting down to business, they will be so glad to have a few manuals lying around.

To give you a rough idea of what I’m talking about, here’s a list of documents that will likely be handy to the survivors of whatever man-made pandemic takes most of us out:

• The power plant operation manual
• A procedural guide for safe corpse disposal
• The zombie extermination guide
• Pharmaceutical reference sheets
• Farming for Dummies
• A quick guide for arming a nuclear warhead so you can finally end those pansies on the East Coast and that meddling old woman
• The beer brewing handbook
• The Vault Dweller’s Survival Guide

Video gaming companies are already providing guides, video tutorials, and detailed simulations to help future survivors learn how to make it in a post-apocalyptic world. But, as Historian Ted Levison points out, users will need the more practical information. And, that’s where technical writers come in.

We are potentially writing the manuals that survivors of the future will desperately need. Well, not me. I’m writing about Internet security, and there’s no Internet access after the Apocalypse. Unless the Apocalypse is Skynet, in which case, the Internet will be restricted to terminators, and they definitely don’t read manuals.

My point is that the printed manual will have its day, and that day is the day after the day everything goes straight to Hell.

Note: The post If No One Reads the Manual, That’s Okay and its related comment discussion are genuinely worthy reads. Though the post inspired this satire, it is not part of the satire.

I recently received a suggestion to add the word “unique” to the phrase “Type a view name” in one of our user manuals. The edit would result in the phrase “Type a unique view name.” I should clarify that we already use the word “unique” in a similar topic, so the suggestion was more for the sake of consistency than anything else. But, it gave me something to think about. I don’t think adding the word “unique” actually improves the user experience. And, I think it is a good example of how we should divide user assistance between the help, user manuals, and the interface.

In this particular case, the user assistance is already provided in the interface. When the user tries to save a view with a name that is not unique, we give them a nice little warning that the view name is already taken. This is perfect. The warning gets the user back to their task with just a single click to acknowledge the warning. We are assisting the user at the first moment they are likely to need assistance, which is when they actually make the mistake. And, the warning covers all the right scenarios:

• view name is already in use
• view name is reserved by the system
• the user doesn’t know the view name must be unique

So, why shouldn’t we add the word “unique” to the help or manual? Consider the conditions that must exist for the word “unique” to be useful:

1. the user must read the manual or help before performing the task
2. AND the user must remember that the view name must be unique
3. AND the user must know whether the view name is already in use
4. AND the user must know whether the view name is reserved by the system

Those are a lot of conditions. The first two conditions don’t jive with what we already know about common user behaviors with documentation - users muddle around before they read, and then they just skim. And, the last two conditions are hampered by the UI itself - the list of default views is already so long it scrolls, which makes it impossible for the user to quickly see which names are taken.

I know this is only one word and digital ink is cheap. However, as we get closer and closer to globalization, I can’t help but think that maybe every word should carry its weight. I suppose the counter argument could be that the documentation is more precise and therefore more complete if we specify that the view name must be unique. But, if it’s not useful, does that completeness matter? Especially when we’re paying to translate docs by the word?

I confess - I avoid writing in this blog because I am concerned that I have nothing of value to offer. I worry that the only people reading it are people I work with out of some misplaced feeling of obligation. And, I worry that everyone is thinking this:

….some people have a desire for an audience in advance of their ability to provide that audience with something of value.

Oh God! Not that! Please don’t read my blog and think THAT!

That comment was a response to Mike Hughes’ post, Why do people listen to me? I was fully prepared to dislike the guy that wrote the comment, since it hit way too close to home. However, the guy, Milan Davidovic, also wrote a followup post on his own blog, which I found quite encouraging.

Milan thinks writers should practice out in the open, for themselves, not for the sake of an audience. He believes that if a writer just happens to produce something people can use, the appropriate audience will find it. And, if a writer never produces anything “worthy,” so what? It’s their blog, or podcast, or twitter feed, or whatever. That’s a powerful thought and it’s exactly what I had in mind when I started this blog, before I became paralyzed by fear and overly worried about every post being “good” according to someone else.

That “build it and they will come” attitude seems to be the philosophy of all my favorite bloggers too. They seem to be okay making mistakes, admitting weakness, or just blogging about what they don’t know and wish they did. They are fearless. And, I love that! So, I’m going to try being more like that from now on.

The projects I worked on at the end of last year required a lot of face-time with coworkers and a lot of thought. I worked on a use case approach to move documentation up in the development cycle. I also worked on improving the user experience with embedded assistance. These were the type of projects that expand my role as an information developer. And, they required a lot collaboration with other departments. But, despite all the work I did, I produced very few actual results. And, when my suggestions couldn’t be implemented or the use case approach couldn’t be carried out due to scheduling, I felt that I had been left empty-handed.

I now realize that these projects are actually investments. Over time, I believe they will pay off. And, to be fair, there were several small successes along the way. With our first attempt at the use case approach, we did write a lot of conceptual information early. Plus, we now have embedded assistance recommendations that are firmly grounded in customer data, which is good.

However, I recognize that to be happy at work, I need more clear successes and I need better measures for success. So, this year, I plan to diversify.

In 2009, I’m going to:

• Pursue projects where I have more control over the outcome

  I plan to work on technology and process problems that only affect the documentation team. For example, I am working on setting up a lab environment for my product and I am documenting the process of installing new builds of the product.

• Focus on personal growth

  I want to get back into self-education and start learning for the sake of learning, not just for the sake of doing. I also want to invest more energy into improving my work habits and professionalism.

• Document my efforts on “investment” projects as a measure success

  I think if I create a running log of my efforts, I can look back and say, “Sure, the outcome is not what I had hoped for, but I made a good effort, and that effort is valuable in itself.” My coworker, Mark Wallis, pointed out that you cannot rely on success as your only measurement, because you cannot guarantee success. I think he’s right and I’m going to work on that.

I don’t want to stop working on “investment” projects, because I think they are important. But, collaborative efforts are not always comfortable and the results of an investment project are not immediately apparent. So, to protect myself from cynicism, and to get back in tune with the optimism I first felt when I started this career, I’m going to give myself more opportunities to succeed.

I recently learned about a DITA specialization for contextual help. Being a good little information developer, I decided to give a whirl.

I immediately got this message:

This DITA specialized document type is not supported by the Authoring Tools development team.
Press the F1 key for online help on the tags and see the DITA XML Guide and Reference for how to use this document type.
For support please see: https://intranetlink

Um. No.

I didn’t have internet access when I got the message, so I couldn’t follow the link. And, I wasn’t sure I even wanted to follow that link. Why do I need even this specialization? The regular ‘ole concept, task, and reference topics had served me just fine in the past. If my tool won’t support it, isn’t that a sign?

It seems we spend a lot of time and energy creating and learning new tools and methods on the premise that we’re getting back to basics. We’re going to get everyone on board. Everyone is going to start speaking the same language – finally! But, “don’t worry, it’s extensible,” we say.

We immediately create a butt-load of specializations, fragmented guidelines, and workarounds so that we can force our newly-adopted way of doing things into the work patterns we already know. Then, we excuse ourselves from sticking to the basics, because, well, they’re too basic. And then, our tools stop working.

Web syndication is a great example of this. The whole point of RSS (Really Simple Syndication) was to have a standard format for syndicating content on the Web. However, we now have a dozen or so flavors of RSS, plus a totally different format called Atom. We have different groups that manage “standards” for these various syndication formats. And, of course, we have compatibility issues in the tools, all for the sake of a format that was supposed to be simple and, well… standard.

Is this where DITA is headed? I hope not. I think not. We currently have just the one standards committee, the Oasis DITA Committee - that’s a good sign.

I suspect that when I do figure out what’s so special about the contextual help DITA specialization, I’ll be singing a different tune. But, I couldn’t help but be reminded of this phenomenon that seems to send us all drifting towards chaos and comfort, even when we’re trying our best to get on board and get organized.

I’m not advocating that we let loose the hob goblins of styles, standards, and rules. But, I do wish we could all be a little more diligent about keeping exceptions as exceptions, and stop making every exception a rule.

I’m the official grunt in a new initiative to adapt use case methodologies to DITA - compliments of Dr. Mike Hughes. And, I must say, this is a really cool project.

Sections in a use case line up pretty nicely with DITA tagging available in task topics. Our plan is to fill in all the sections that answer why, when, who, and what. We fill in the “how” when developers actually create the UI. Okay, I admit, when I explain it here, it seems obvious to do it this way. But, it also seemed obvious to ask “why did the user click help?” Yet, I managed to reliably mess that up.

So far, this project is going great. I already have two fleshed-out topics, which is significant considering that my development team just scheduled their first stand-up meeting and release is expected to be a year away.

I feel very committed to the best little helper I can on this project. I think the more I can write in this UI-agnostic environment, the less stress I will have near release time, when everything is “nailed down” and then changed three times for good measure.

You can read all about this cool new approach in Mike Hughe’s article, Use Cases for User Assistance Writers, on UXMatters.com, at http://www.uxmatters.com/MT/archives/000329.php.

Collaborative walkthroughs are a technique that my team used while rewriting our Help and adopting DITA. We believe that we were able to improve the user experience by improving the collaborative experience. Here is my presentation on our use of this technique.

Dr. Mike Hughes’ article, which I reference in the presentation, is available at UXMatters.com: http://www.uxmatters.com/MT/archives/000211.php

You can download a PDF of all the slides in my presentation here: Collaborative Walkthroughs Presentation Handout.

You can also download a higher quality version of the video presentation in ZIP format here: Collcaborative Walkthroughs Video.

I apologize for the bad sound quality in some places. I think replacing my soundboard might improve the quality of the voice over, but I want to share this with you now.

The third writer says, “You know, they really should write a warning on that.”

This joke is courtesy of my friend, a developer (of course).