When my colleague and I were preparing a presentation for an internal conference on this subject, he said something that has stuck with me. He said, “The goal of the project is to make the user successful.” I added to that: It’s not to write code or validate code. It’s not even to ship a product or make money (of course, this last one is especially true in a non-profit organization). At least, it shouldn’t be these things.

The goal of a project is to make the user successful at what he wants to accomplish.

Go ahead, read that previous sentence a few times. It’s one that would do well to sink in.

This isn’t to say that, for example in the case of software, that the code isn’t the main output of the project and is therefore the most important deliverable. But the code is a means to an end. And if you’re concerned about helping the user reach her goals, then you’ll be more likely to make the money, or at least be a trusted partner if you’re not out for a profit.

Communication Breakdown

As mentioned, breakdown in language is a barrier to users’ success. I’m not talking about localization problems, though that subject is related.

I have a couple of examples just from this week. First, while I was getting some answers to questions, a QA engineer suggested to me that we needed to have a glossary for the short guide I’m working on. His main concern that he had found some people in the customer department had different definitions for certain terms. The application used the terms a certain way, so it would be important to set those terms out the way the application uses them to reduce confusion.

Second, a user of a different application ran into trouble with a feature and thought the entire feature didn’t work. Part of the problem was the infamous error message. It was nonsensical to this user and added to his frustration. When I read the message, I was able to pick out what it was saying, but I agreed that it was very unclear. I have no idea who wrote the message, but what I think the person was trying to do was use one sentence to account for all possible input formats for this particular field. The unfortunate thing is that in explaining in these terms what was acceptable, the message didn’t tell this user what was actually wrong with what he had typed: the inclusion of a single illegal character.

The reason I became aware of this second situation was that the QA lead asked me to rewrite the message. So I rewrote it to show acceptable formats instead of describing in general terms what was allowed.

The Importance of Text

This is one of the reasons I strongly believe that technical writers should be involved in crafting user interface text and error messages. With our user hat on as when we write documentation, we can help put together UI text that makes sense and lets the user know what to do next.

Text is an essential part of nearly every interface. Imagine going to a website to shop, only there was no text. You would probably see thumbnails of the products, but you wouldn’t know how much they cost or where to enter your credit card information. You probably wouldn’t even know what site you were on if it weren’t for the URL.

Granted, there are some common icons on the Web that are widely understood, such as a shopping cart. But many times, icons are still accompanied by text to make little room for misunderstanding.

Designers and Writers Unite …

This is an opportunity for designers to partner with technical communicators to improve the usability of products through clear, effective text. Admittedly, many technical communicators are in this field because we’re word nerds. We think it’s important to choose the right words.

In our presentation, my colleague told of an experience he had where he was brought in to work on a project that was rated badly by its users. He found that the main problem was that the text that the developers had used in the interface didn’t make sense to the users. While it was technically correct, the average user didn’t have the right vocabulary to understand it. After my colleague spent some time with the designer changing the text and a product update was launched, the product was rated as much more usable. The users had a much more positive experience from that point on.

Wrap-up

When teams think in terms of making the user successful, I think priorities will adjust and emphases become more balanced. Simple, clean interfaces are important, but without instantly decipherable text on those interfaces, users can’t accomplish their goals. And this affects the bottom line—making (or saving) money or being a trusted partner with your customers.

No related posts.

The Enthusiastic Developer

Sometimes, the work performed is on the background functions; while it affects the user interface, it’s not something the developers can demonstrate through the interface. In this particular meeting, one of the developers explained the theory behind something that was very technical in nature and happening behind the scenes.

Developers are great, and they do some amazing things with code—especially the developers I work with. But I think that sometimes they fall into the same mindset that we all do from time to time, namely that because they are extremely interested in what they’re doing, everyone else should be too.

The Less-Than-Enthusiastic Audience

This customer is normally very energetic and has a quick sense of humor. I noticed while this explanation was proceeding, the customer—to whom we were connected via video conference—appeared to be losing focus. When the developer asked him if it made sense, he responded with a barely audible monosyllable. It was very unlike him. He seemed to come back to life a bit after the explanation was over, and the meeting ended soon after that.

The What Is More Important Than the How

I relate this not to poke fun at developers, rather because it emphasized to me a principle that’s important for technical communicators: The audience doesn’t always care about how things work. They care more about what they need to do to make it work and that it works.

It can be the coolest database acrobatics ever conceived, but if it’s not going to in some way help the user, it’s superfluous information to them, which means information that dilutes and gets in the way of the important information. And believe me, I’ve had a developer explain some database functions that were pretty sweet in their ingeniousness and required intricacy.

It can be easy to provide information to users about how the product works, about why it behaves the way it does. I wouldn’t call this a trap, but whatever it is (a puddle?), I fall into it myself. Some information just doesn’t make sense if you don’t explain the how. For example, in some release notes I’m working on, I’m including a known issue about the way a certain field behaves. I suppose I could explain only what they need to do to get around the problem, but it’s hard to do without providing a bit of the why the problem is occurring. As I think about it, I’m sure it’s possible to explain just the what and not the how and why. But that’s the dilemma I’m in.

Still, that customer’s sagging head during the explanation comes back to my mind. It’s not that the developer’s explanation in and of itself was particularly technical—at least not overly so, because he was deliberately trying to compare it to something easy to understand—and he even tried to involve the customer in his comparison. But it still came down to the fact that he was discussing something that was beyond the realm of relevance for the customer.

Wrap-up

Information about how things work has its place, certainly. But it’s usually off to the side or at the end in some appendix-type spot. If you find yourself including the how, try taking it out and putting it off to the side or at the end. Then go through the text without the how in there and see if it still makes sense. I’m betting that in most cases, it will. So I’ll be trying that myself to see if it’s a way to tighten up the content.

No related posts.

Of course, I changed my mind and decided to be a writer. I would still draw and doodle, and I even had a cartoon strip in the university newspaper later, but I tended to write a lot more than draw.

A couple of weeks ago, I decided that I wanted to get back to drawing on a regular basis. The best way to fit that into my schedule and make sure I actually did it was to spend a few minutes each night sketching and drawing before I go to bed.

I have received compliments on and some small awards for drawings before, so I suppose I’d say I have talent in the area. People have said, “I wish I could draw like that.” For years, I’ve been convinced that most people could “draw like that” if they really wanted to.

Okay, maybe they wouldn’t draw exactly like me, but they could draw well. My opinion is that many people can develop artistic talent if they tried it and kept at it.

A big part of drawing well, I realized about the time that I started sketching again, is observation. When you see a drawing done by a child, it can look wrong and twist your eyes a bit. If you think about it, you may decide that it’s because the perspective is wrong, or objects are the wrong sizes in proportion to each other. That’s because often, children haven’t quite learned to transfer what they see onto paper the way they see it. (Some adults do that on purpose, but I’m not getting into a discussion on interpretation and personal perspective here.)

I believe that if a person were to take the time to really observe the world, he could draw it—with some practice, perhaps. I’ve never taken an art class with focus on anatomy, but I look at people and think about where their joints are in relation to each other and where the curves and lines are, so I can draw decent human figures. Drawing well can be helped by also observing what other people create and analyzing their techniques.

For me, drawing and writing have a number of parallels. One of these is the fact that doing it well takes careful observation, to see things as they are, and even to see beyond what’s apparent to the eye or other senses. When we say someone is observant and we’re not being sarcastic, we’re usually saying not that the person sees what’s apparent, but that she sees what’s below the surface.

Particularly, in technical communication, much of our work is about observation. We interview, we watch users, we ask ourselves questions, we get as much of the audience’s perspective as we can so that we can provide the right information—so our writing is effective. Much of the time, good content means getting past what’s apparent, especially if it’s what we think is apparent.

So what I think about drawing applies to writing too: If you want to do it well, take the time to look around and observe. Look beyond the surface, make connections, and establish relationships. You may find a talent or reach a higher degree of effectiveness and satisfaction in what you’re already doing.

No related posts.

One of the sessions I attended was the basics of usability presented by a usability specialist and an interaction designer. The session included an exercise that illustrated why usability testing is important and how it can be done early in the process with little expense. The presenters divided the attendees into several groups, and each person received a role as product manager (or customer), user, program manager, business analyst, or interaction designer. Each had certain goals to meet with the product, and then we had to create prototypes consisting of sheets of paper and sticky notes written on with markers. At the end of the designated time, the user had to come in and try to accomplish certain tasks using the prototypes and navigating them with his finger.

I was the product manager for the group I was in, and I had some knowledge of the subject matter that the application related to, but sometimes the business analyst, program manager, and designer would ask me questions I didn’t have the answer to. Still, it was a fun exercise. And one of the points was that usability should be owned and encouraged by everyone on the team. We also found that at times, we overlooked very obvious things that were necessary in the interface.

My opinion of why managers generally resist or overlook usability testing is that it can be seen as churn. The manager may say, “We already designed, developed, and tested that functionality according to the customer’s specs [or user stories, use cases, or whatever you happen to call them]. If we do usability testing, we’re just rehashing the same steps, covering the same ground, instead of moving on to new development.” The presenters suggested that people may also hesitate because they believe the myth that usability testing has to be a big production with expensive labs.

One of my colleagues from the User Education team works with the presenters, and as the usability specialist spoke, she talked about how she would keep him informed of the results of the usability tests. She admitted that not every problem discovered in the testing can be resolved by the development team, so that’s when she called on the writer to lessen the problems by providing good documentation.

I was thinking about the topic recently of where usability and documentation meet, so this session caused me to think about it further. It’s kind of a funny concept because I would say documentation is part of usability, but when we’re talking about the usability of a product itself, the documentation has to meet it somewhere. The project team can do only so much given aggressive schedules and limited money to perfect everything. So the documentation picks up the slack, so to speak.

This is not to say that documentation is a product crutch. An interaction designer I know who used to be a usability specialist once gave me a pin-on button that says, “No, you can’t just explain it in the manual.” That is, the product has to have its own merit and not rely on the documentation to explain the user’s way through all the problems. That’s probably something to keep in mind when we encounter usability problems in the products we work with; rather than just document it, we should speak up. We stand with one foot on each side of the line between user and project team, so we can give advance warning of usability problems.

As technical writers, we have an inherent interest in usability. We approach a product thinking like the user, considering how the user will use it, so we easily catch usability problems. And the less usable the product is, the harder we have to work to explain it and how to use it.

At the risk of repeating myself, I’ve mentioned here before that I dislike hearing someone say that if the product is designed well or is intuitive, then it doesn’t need documentation. I’ve got news for subscribers to this philosophy: “Intuitive” is a subjective term, and it can be persuasively argued that nothing is really intuitive because we have to learn pretty much everything from the time we’re born. My point is that usability goes only so far before documentation has to step in anyway.

What can you do when it comes to usability testing?

• First, speak up. Give your voice in support of it. Talk about the merits. If you first need to learn about the benefits of usability testing, research it so you can speak with confidence.
• Second, get involved in the testing. Offer to assist whoever takes the lead. If this is you, then you’ll obviously be involved, but if there’s a usability specialist or designer in charge, explain why you have an interest in the results of the testing. I’m sure they’d be happy to have help.
• Third, understand what the team won’t be able to change and decide whether you need to fill in the gap.

One designer I work with has been trying to arrange some informal usability testing on a set of features, but things have been getting in the way. But I’m excited that he’s trying to do it and that he’s willing to have me there to observe. The project can only benefit, even with looming deadlines and limited funds. And the documentation can only benefit, too.

No related posts.

Still, I personally prefer to write longer posts much of the time. Most of the time, “longer” means just a few paragraphs, but at other times, I like to use the post to explore my thoughts. It’s hard to get into the guts of an idea or concept in 100 or 200 words. Just because I like writing, it can be tempting to keep writing. The trick is to actually go somewhere with my comments rather than to follow the train of thought until it ends in the middle of the woods, instead to end strong and with a point that connects with people.

I personally don’t mind reading posts or articles of six or eight paragraphs. To me, that suggests that authors are going somewhere with their thoughts, supporting their ideas with experiences and events, and going beyond a surface commentary and analysis.

Notice that I said six or eight paragraphs. Much more than that, and I’m going to think I don’t have time for this and go elsewhere.

I asked a question on Twitter a couple of weeks ago: “If you read blogs, what makes a blog post interesting to you?” I received just a few replies:

• “Topic/theme of interest to me, speaks to me, about something I want to learn about”
• “the personality of the writer. I like wit that isn’t prententious”
• “What makes an interesting blog post: Tell me an idea or insight you’ve had, and why it’s important to you”

So length may be a factor in engaging people, but it’s certainly not the first thing. I’m not saying that Tom Johnson agrees with me here, but long posts are not one of his seven deadly sins of blogging so far (they’re listed in the first paragraph of his post on the first sin). Writing on topics that are interesting, that connect with people, is the key and the challenge.

If you hate long posts, let me know. If you love them, let me know. But I hope you’ll forgive me if I’m interested enough in a topic and analyzing it enough to write a lengthy post about it.

No related posts.

I admit that I’m among those who would love to get free stuff from the Web all the time and be able to use it in any way I like. To create the gryphon image on my site, I used a couple of photographs from sites that provided license to use and modify the images. It’s great to have things that wide open. There are those selfless souls who place their intellectual property out on the Web and allow everyone to reuse and repurpose it without limits—but I would guess that there are more people like me who like to take advantage of them and at the same time don’t want to invest our own time and resources to offer what we do for nothing.

Many of us are possessive of our content. Businesses pay people to create content, so it only makes sense to want to charge for it. Or I went to all the trouble to write it or draw it with my own time and money, and people should be willing to reward me. Or at least acknowledge me.

It has been an amazing phenomenon to me that we have gone from a society that creates mainly sellable goods to one that creates less tangible products like text and images. There’s still a vacuum in your closet, a microwave in your kitchen, and a computer in front of you. But much of what’s produced by professionals these days is that which is produced by the mind rather than the hands in a manner of speaking, hence the term intellectual property.

I thought it and put it in writing. I imagined it and created an image. Therefore, I own it. I inherently own the rights to that material, and you don’t.

Sure that I wasn’t the first to think about the illusion of “the free Web,” I googled this term and found an article from PC Magazine last May entitled “Is the Free Web about to Expire?” While making a strong point, it seems that this article is talking about consuming content, though, not perpetuating it, reselling it, or changing it.

Even if creators of intellectual property don’t charge for the use of something, we have to realize that just because it’s out there and can be freely viewed, license may not be provided to do what we will with it. I think the concept of the “free Web” has given some people the idea that if they can get it, it’s okay to reuse it. But in this day and age, when people look for reasons to take others to court, it’s better to be careful than to get that perfect image and hope that no one ever calls you on it.

One of the benefits of being a technical communicator with various skills—writing, illustrating, video—is that the more skills you have, the less you have to rely on others’ intellectual property. For example, when creating illustrations for quick guides, I’d rather draw something in Illustrator myself so that I know I have the rights to use it and modify it. If you become proficient with such tools, then you can whip up something that’s more than decent inside an hour.

When you think of the free Web in the context of not having to pay for something, remember that there’s another aspect: Nearly everything that’s on the Web belongs to someone. And because the Web is so widely accessible, it’s entirely possible that if you abuse someone’s rights regarding their intellectual property, they will discover it and exercise their rights.

No related posts.

What he’s talking about is database diagrams (which I’m more than happy to leave to him) or notes from talking to people involved in the business process. I did discover recently that a business analyst put together what he called a quick guide, but it was mostly screenshots and very little text. It didn’t really explain steps. So guess what I’m going to be doing in the near future.

Project teams can accumulate quite a load of documentation over the lifecycle, even aside from any end-user material. In projects I’ve worked on, I’ve seen the following (and probably others):

• Requirements documents
• Concept documents
• User stories and accompanying comments
• Bug tickets and accompanying comments
• Excel spreadsheets with matrices or database code
• Prototype notes
• Wireframe notes
• Visio diagrams of workflows or database relationships
• Samples of legacy reports

I’ve drawn on many of these for my user assistance material. It can be a lot to sift through, and sometimes I settle for asking someone questions rather than wading through the files (gee, that sounds like most of mankind—am I being hypocritical here?). I suppose it’s better that a team have ample documentation than a shortage.

My point is that if your team is going to the trouble of producing this stuff, take advantage of it. On the other hand, lately I’ve felt a little guilty if I wanted to ask, “Is there a document covering this?” as if I’m saying, “I’m antisocial and don’t want to talk to you. I’d rather sit at my computer with headphones on and read my screen, living in my own little tech writing world, than conduct an interview with you.” I’m sure that’s not what the other person would think I’m really saying. In fact, in large part, the developers I work with are as accommodating as they can be and very willing to answer my questions.

There’s a happy medium to be found, I’m sure, as with most aspects in life. If a project has a pile of team documentation, it can be a rich mine full of resources for understanding the product. However, the point may come where you get little return on the time investment and it’s simpler to ask someone. Provided that getting some face time and the answers you need takes less teeth-pulling than going through that project documentation.

No related posts.

No related posts.

Sometimes that kind of bouncing is unavoidable, such as when my team manager needs me to take care of a communication task or some release notes need some last-minute updating. I gave myself some leeway in the goal. But the overall goal is to spend three- to four-hour chunks of time on a particular project so that even if I switch tasks within a project’s work, at least I’m not having to change my mindset. Because we set goals for each quarter of the year, I’m currently in the quarter where this goal applies.

It’s tough to do. I still find myself bouncing between projects more than I want to or intend to. I think working on this goal has helped my productivity some, but I’m coming to realize that what I’m lacking is planning. I need to plan out those half-day chunks of time so that when I know I have one or two tasks to do, I don’t finish them up and then ask myself, “What else can I do on this project?” Doing that, I probably lose whatever productivity I have gained by continuing to work on the same project.

What I probably need to do is spend a few minutes at the end of each day looking at what I need to do the next day, and then plan out those half-day chunks of time. I think I’ve heard of people who spend a few minutes either at the end of the day or at the beginning planning out what they’re going to do. Those few minutes will probably help the productivity go up. I think I’d rather do it at the end of the day while I still remember where I was and when I’m not distracted by the email that’s accumulated.

Thanks for the idea. I’m glad we talked this over.

No related posts.

Michael says:

We tend to keep a core of loyal members (I love all of you), but that has created a demographic problem: A lot of us are older and will be retiring in the coming decade. We are losing our “next generation” of STC members. The upshot is that decisions about how to grow the society are being made by those who often lack the perspective of what the target population wants. Ouch!! OK, that one hits this sixty-year old boy too, so hold off on the flames.

You Talkin’ to Me?

I consider myself among the “next generation” that Michael talks about. Depending on whom you ask, I was born during the somewhat fuzzy transition from Generation X to Generation Y. I graduated from college about four years ago and have a grand total of five years’ experience or so in technical communication. If I’ve ever come across here as anything different (the most likely being even more ignorant than I really am), then you have my apologies for deceiving you.

I agree that the best people to know how to reach the (shall we say) newer generations of technical communicators are themselves. But is replacing the current leadership with a bunch of twenty-thirty-something, forward-thinking, tech-savvy hotshots the answer?

Maybe.

But if you change things completely, you lose the older folks’ experience and longer view, and they can be every bit as forward thinking as the subsequent generations. Some of us do ride behind the crest of the wave. (Not everyone can be in the front rank, right?)

I’m not volunteering for general STC duty. I’ve got my hands full as president of a chapter, and for now the community level suits me just fine. Perhaps if I can fix all the world’s problems on a local level, I can turn around and fix them on a general level. But don’t hold your breath.

The Current Offering

One of my aims as a chapter president is to find out what the current members want out of us. If we can give them what they want, we stand in a better position to attract previous members and new members. In our August board meeting, what people want was one of our focuses, and we used that to start planning our program of events for the coming months. We’re going to implement a questionnaire to get specific feedback from members.

As I’ve said before, I want support for the chapter level. The Leadership Community Resource (LCR) group is lining up mentors for the chapters, but an older member of my chapter says that this song has been sung before. I hope that STC follows up on this. But still, that’s my perspective as an officer and an indirect benefit for the rest of the members.

The thing that troubles me the most is that the majority of the things that are free with STC membership—the things STC advertises—have more to do with finding a job and career building than with improving our actual day-to-day work as technical communicators. Those kinds of things, like webinars and the annual conference, are costly if you have to pay for them yourself. So I don’t blame people for wondering what they’re getting out of a dues hike when they still have to pay for what they want out of STC.

Even the documentation that STC provided for leaders in the LCR suggests that of the costs to serve a member, one-third belongs to the publications. The other two-thirds amounts to what appears to be overhead (and the “find a job” kinds of benefits). True, many people join for the publications, but $175—or more, soon—is a lot to pay for a couple of subscriptions.

The Million-Dollar Question

This isn’t Sam’s Club or Costco. People don’t join STC to get discounts on a conference or webinars. They join to get direct, concrete benefits. It comes down to goods (I’ve got something in hand I didn’t have before) or services (you do something for me so I don’t have to do it myself or something I can’t do for myself). Publications fall into the first category, and community relations fall into the second. But that seems fairly limited.

So of course, as Michael suggests, a big question is what will get the next generation of technical communicators to join STC?

Now remember what I said before. I consider myself among the next generation. So when I talk about “what the next generation wants,” I’m speaking for myself.

I’ll acknowledge that the next generation wants lower dues (or for our employers all to pay dues for us). That’s one of the first things that will help draw people. I’ve read a lot of back and forth on that subject, and I acknowledge that “lower taxes” is the watchword of every generation. But for many people, it comes down to what you’re getting for your money, what goods you have in hand or how your life is being made easier by services.

At first, lower dues will be attractive only to those who want to belong to STC anyway. To reach those who don’t intend to join STC now, I think we need a couple of things: to drive innovation in our field and to foster community and collaboration among members.

Drive Innovation

For years, software vendors have been telling technical communicators how to do our job by what they give us. Unless we turn into programmers ourselves (admittedly, there are tech writers at all levels of programming skill), we’re at the mercy of companies like Adobe, MadCap, and ComponentOne. I would like to be proven wrong, but I doubt their strategies are formed by technical communicators. We are still limited mostly by software product managers’ concept of technical communication. And it’s the bane of our profession that project and product managers don’t understand tech comm.

STC should be taking the lead by developing ideas, maybe through a committee or task force, for the products that technical communicators need. We shouldn’t be leaving it up to non–technical writers to tell us how to deliver documentation and training. We should be telling them what we want in as united a voice as possible and let them scramble and compete to give us what we want.

Foster Community and Collaboration

Some loud complaints were voiced when STC retired the forums. I imagine that this is because many STC members wanted a place to connect with each other. Further evidence that people value STC for the community is the fact that I have heard people say they get the most value out of the SIGs, and those are virtual communities. STC membership is so spread out that it’s vital STC take advantage of and provide ways to network and build professional relationships virtually.

I think STC ought to facilitate mentoring among technical communicators and give us a way to show each other what we’re doing and get feedback about it. If these things are out there on a society level, I’m not aware of them.

I understand that we’re all professionals and time is limited. We can’t give everything away; we have ourselves and families to support. But think of all the open source development projects out there. People contribute to things because they’re interested and enthusiastic. Let’s make a place for enthusiastic technical communicators (there is such a thing) to come together virtually and really make a good name for our profession.

Another aspect where STC could bring members into teams and communities is to find projects for us to do. Task forces are often assigned to gather information and give input. They also ought to give members a chance to work on projects, showcase the profession, and add to their portfolios. As an organization using connections and influence, STC could find opportunities where individuals couldn’t. And people who don’t want to volunteer as officers because they see no return for their effort may be more interested in participating in projects where there is a concrete output, as well as enhancement to their expertise and portfolios.

If much of STC’s cost is overhead, maybe we need more communities, projects, and volunteer leaders and facilitators to guide things along and less paid staff. I hate to suggest that anyone lose his or her job, but it’s worth looking at to see if STC government could be reorganized to use more volunteers. (Sounds like a job for a task force.) Just a thought.

Show Me the Value

In recent months, the discussion usually comes down to value. In fact, the other night after our local chapter event, one of the members told me that she is the representative STC member for her team at work. Her employer is paying for her membership but no one else’s, and they want to know what they get back from STC for their money. They have every right to be asking that. I hope this year, our chapter makes long strides toward giving members something to say when employers ask them why they should pay for STC membership. This particular employer doesn’t see enough value in STC to pay for all of the employed technical communicators to belong.

Collaboration and communities are important for the future of STC because they are an important part of life for newer generations. Well known technical communicators are waving their arms and saying social media are the future (and the present) of our field, and if that’s the case, then it ought to be the near—even immediate—future of STC. I’m no social media cyborg, implanting artificial community in my life at every possible opportunity, but that’s where many people in the world are right now. The society also ought to be pointing the direction that tech comm vendors go in their development. We need to arrive at a happy place where employers will pay for their employees’ memberships and see concrete, positive results from that membership in their organizations.

As a member of the “next generation,” that’s what I want out of STC.

No related posts.