I'd Rather Be Writing » communication

The Proximity Problem for Technical Writers

Tom Johnson — Fri, 23 Sep 2011 14:33:59 +0000

Last year I wrote a series of posts about moving from the sidelines to center stage. In the series I described how I transitioned from a low-key, hardly-speaking project member to a key player on the project team, someone with a voice that mattered in project decisions. But recently, with some projects, I’ve come full circle, moving back to that initial position of a fly on the wall.

The changes had a lot to do with location. Previously, each technical writer was embedded in a specific group. Most of us were stationed on different floors, in proximity to the developers, interaction designers, quality assurance engineers, and project managers for each project.

This proximity was useful for staying in the loop with project information, but it did nothing for our technical writing team. We used different tools, didn’t follow a common style guide, and came up with our own processes and content models.

Because we wanted to try to build some momentum towards standards, we decided to consolidate our group, sitting together in the same row of cubes. We were no longer embedded within specific project teams, but rather centralized as technical writers in a common location and shared throughout the organization.

In the previous embedded-writer model, I looked longingly towards our once-a-week meeting with technical writers, holding it as the highlight meeting of the week. But now that we were sitting together, it was like a team meeting all day long. Coordination and morale skyrocketed.

As the weeks passed, we started to form some standards. We decided to standardize our toolset, first of all, so that in case one writer won the lottery and left the organization, another writer could seamlessly fill the gap. After weeks of research, and through the luck of another group that already purchased the solution, we adopted and implemented a new help authoring system. We then attacked our style discrepancies, and quickly adopted a 42-page guide of stylistic decisions.

We were gaining momentum fast, and acquired our own servers to run help, injected a documentation template into the project manager process, formulated a content model for help, designated a team member to be the tools administrator, and more. We were flying as a team. We even stopped holding team meetings because anytime we needed to meet, we could just swivel our chairs and raise an issue. Our close proximity led to a brilliant flow of communication.

In the back of my mind, I knew that we had lost some rapport with the project teams that we no longer sat next to. But it didn’t hit me how detached I had become until, about a year later, I attended a two-hour meeting with one of my projects and found that I had nothing to say at all. All the momentum I had previously accrued as a key project voice seemed to slip out from under me.

Proximity and Communication

Sitting silently in the project meeting, not contributing towards interface text, nor quality assurance, nor jumping in on broken functionality, nor even on training strategies, I realized that my sacrifice of proximity with the project team had resulted in my impotence on the project team. I no longer had the same voice, nor was I someone anyone paid attention to. I had become that quiet fly-on-the-wall technical writer, the one whom no one expects anything from except a help file.

I’ve learned that proximity to any team makes an incalculable difference in the role you play with that team. Grouped together with other writers, we actually formed standards for the first time in years. We felt like a team. And separated from project teams, I fell off their radar, and they off mine.

This, then, is what I’m calling The Proximity Problem. The closer you are to a group, the more you interact with that group. But you can’t be everywhere at once, so you have to choose the group that gets priority. Given these dynamics, is it better to be embedded within project teams or within a technical writing team?

Comparing and Contrasting Benefits

Embedded within project teams, I did much more than technical writing. I logged bugs, critiqued designs, guided project managers with feedback from users, and was generally go-to guy for new team members who want to ramp up on the project. I became a subject matter expert on the app itself, which led to my being a key member with a voice at the table.

Embedded within the technical writing team, I didn’t get sucked into all of these secondary roles. I could focus on my primary contribution: the help material. But not having involvement in other aspects of the project, such as the design, testing, interface, planning, and so on, made it harder to write help. I was often a latecomer to information, finding out at the last minute about upcoming releases and stumbling into new pages with changed functionality.

Sitting with my colleagues is heavenly. We understand our kind. We engage in heated debates about style controversies, and sometimes crack jokes about how bad interface text is. We ask each other questions about Author-it and Camtasia. One of my colleagues even brings in peaches to share, and has his own candy store. It’s comfortable to sit with them, and share in the camaraderie.

But in the larger scope of agile development, this isolation from the project conversations that are happening on an ongoing basis seems to have negative consequences. The isolation away from other writers, as I sit near developers and other IT members, might be worth it for the end result. The problem is that projects are often short durations, so I would need to be nomadic for the model to work, moving from one project group to another as my project load shifted.

Perhaps nomadism would be ideal for help authors. When working on project X, sit next to project X. When working on project Y, sit next to project Y. And yet, even despite the improbability of such an open seating model, it seems archaic in a day of virtual collaboration and remotely located workforces. Why insist that maximum productivity is only gained by rubbing elbows with your team all day long? Surely asynchronous methods of communication, real-time online interactions, and regular meetings using VoIP or the telephone can compete with the benefits of nearby seating.

Alternatives to the Dilemma

Despite the logic of embedding myself with a project team, where very likely I’m the only technical writer present, I’m not ready to give up our new-found team momentum. We’re making a lot of progress towards standards and tools, processes and styles. Once the dust settles, we may return to our former model in which we’re embedded in project teams.

Still, perhaps I’m holding out for another reason: I’m not convinced that proximity is essential to keeping up with project information. I’m not persuaded that there aren’t equally viable ways to gather the same data and interact, because if nothing else, the Internet has shown us how remotely distributed people can be closely connected with each other. The Internet has pulled us loose from our physical relationships, distancing us from those immediately around us and drawing us closer to others whom we never see or speak with. Email, instant messaging, Internet Relay Chat, webinars, podcasts, blogs, websites, text messages — all of this enables communication to take place despite physical boundaries. Theoretically, proximity shouldn’t be a problem. But teams who already enjoy proximity have no need for virtual communication tools, so outsiders often feel the need to participate in close proximity model to keep in loop.

It’s true that proximity does lend itself to more immediate updates. When you’re sitting next to a developer and he makes a shout of joy when he gets something to work, you’re updated. When you’re sitting next to a tester who groans each time she finds another bug, you’re updated (that is, if you ask what the commotion is about).

But it’s still possible to stay updated sitting remotely, away from project teams. And this is precisely because nearly every team in most IT groups uses some form of bug tracking tool, such as JIRA, Team Foundation Server, Fogbugz, or something else. Nearly everything gets logged somewhere, and if we take the time to stay close to it, to follow it as carefully as we might read a novel, tracking comment threads, attending meetings, reviewing sprint plans and roadmaps, checking IRC logs, design and requirements documents, listening each day to scrums — if we did all this, we could circumvent the proximity problem and perhaps even stay more aware than team members in the same cube aisle. That is, as long as distance doesn’t deafen our ears, make us forget our priorities and workloads, and lull us into a false belief that nothing much is going on.

Blog Sponsors

Eight Defining Questions that Shape Content Organization [Organizing Content #29]

Tom Johnson — Fri, 01 Oct 2010 14:13:55 +0000

With recent posts in this series, I started to raise a different question. Rather than asking, how can I help users find this information, I started to ask, how can I help users learn this information? The question you ask determines the strategy you use to organize your content.

This may seem like an obvious point, but it’s fundamental in determining how to organize your content. In looking over different tech-comm-related disciplines, there are at least 8 different questions we are likely to ask:

How can I make this content understandable? (technical writing)
How can I make this content findable? (information architecture)
How can I improve the content and the processes surrounding the content? (content strategy)
How can I help users learn the content? (instructional design)
How can I manage and re-use the content? (content management)
How I persuade the audience toward a particular view of the content? (rhetoric)
How can I make the application more usable? (user experience)
How I can I increase sales and adoption of the application? (marketing)

(Let me know if you disagree about these questions, by the way. I find that distilling a discipline down to one central question helps me better understand what the discipline is all about.)

Each of these questions informs or shapes how one should organize the content. This is just common sense. Your content’s organization should reflect your objective. If your objective is to help users learn the content, you’ll choose a different organization than if your purpose is to make the content findable.

Your objective determines how you organize your content

For example, a learning objective may prompt you to chunk the material into 5 minute learning modules, with a focus on only the most common tasks. You might then break out the modules into levels that users can proceed through.

But if your objective is to make the information findable, you may have a different organization. You might have different navigation facets that the content is tagged with. Those facets can form the navigation on the homepage. As users drill into the facets, a second-level navigation might appear.

If your purpose is to make the application more usable, you might focus most of your energies around interface text, context-sensitive help, information pop-ups, error messages, navigation text, button labels, dialog boxes, and other helps the user will see while in the application.

If your purpose is understandability, you might focus more of your efforts on illustrations, screencasts, screenshots (with callouts and captions). You might carefully structure the content in a hierarchical way, and use bulleted lists, subheadings, examples, and other aids to help make it easy for the user to understand.

It’s more problematic, though

This may seem all like common sense, but the reality is much more problematic. Technical communicators often have multiple purposes. If you distinguish a technical writer from an instructional designer with the two questions above, one may want to punch the other. The purposes overlap. Of course technical writers want to help users learn the application. Of course instructional designers want users to understand the content. Who doesn’t want to improve the content and make the processes surrounding content creation, approval, and delivery more efficient? Who wouldn’t be interested in improving the user experience in the application? Technical communicators do all of this.

Do competing objectives have mutually exclusive organizational models for the content? Can I satisfy multiple purposes with the same content organization? To some extent, yes. But that’s where it becomes challenging. Maybe the information architect’s question becomes the most important one to ask — how can I help the user find the content he or she needs based on differing purposes? How can I present the material to the user in the right way at the right time to fill my current objective? If one user wants to learn, another wants marketing material to sell the app to his or her department, another user wants to find an answer to an obscure question — how can we organize the content to meet all of these needs?

To further explore this question, I’ll probably need to move from the abstract to the concrete and apply it to my initial Swordfish project scenario.

Blog Sponsors

Communication Preferences and Jane’s Voicemail Message

Tom Johnson — Mon, 16 Feb 2009 05:55:25 +0000

Jane recently changed her voicemail message to the following:

(20 second voicemail)

I nearly choked while laughing the first time I heard this. What she says is true. I usually end up listening to her voicemail messages for her.

The proliferation of communication formats provides more possibilities for how we communicate. With all these format possibilities, we need a few best practices.

As a best practice, if you’re trying to maximize your communication with another person, you should generally respond in the format the queries come. If someone emails you, send them an email back. If someone calls you, call him or her back. If someone instant messages you, return with an instant message. If someone replies to you on Twitter, send a Twitter reply back. If someone comments on your blog, respond in a comment below their comment. If someone writes you a snail mail letter, dig out the old pen and paper and find a stamp to reply. If someone texts you, text them back. Why? Because that’s their communication preference, and you’re more likely to succeed at communicating with the person if you align with their preferences for communicating.

Additionally, your response can be approximately equivalent to the inquiry, for the most part. If someone writes you a two-sentence email, you don’t need to respond with a novella. Part of the appeal of Twitter is the 140 character limit.

It’s certainly not a requirement to cater to someone’s communication preference. If communicating successfully with that person isn’t a high priority, let them align with your communication preferences. But at least let them know what your preferences are, as Jane does in her voicemail. (By the way, the voicemail has worked well so far. People have stopped leaving her voicemail messages and are actually sending her email instead.)

What are my communication preferences? I prefer email for most communications. Except when I’m driving, and then I prefer the phone. I find instant messaging somewhat annoying, unless I’m bored and in the mood to chat. Twitter is fine unless the conversation clearly requires more than 140 character exchanges. But generally I don’t mind the format. I understand that each person prefers a different medium for communicating, and I try to accomodate that. It all comes together into one on my BlackBerry anyway.

Blog Sponsors

Twitter Part II –- One Step Deeper

Tom Johnson — Fri, 05 Dec 2008 22:29:14 +0000

Webworks and Twitter -- Innovative uses of Twitter with documentation

Earlier this week I asked how others are using Twitter in their documentation and branding strategies. Alan Porter at WebWorks wrote me with details, saying:

As you know we have a branded Twitter account (webworks_com) that we use for product announcements, information on speaking engagements, webinars and just general company updates. We also have a hashtag set up for information related to our annual RoundUp users conference.

We are also encouraging our partner companies, and consultants that we work with, to set up Twitter accounts, and several of them have set up accounts and are using them.

We actively follow all the top Tech Doc twitter accounts like yourself, Sarah O’ Keefe, Scott Abel, Anne Gentle, Paul Mueller, Alan Houser, etc., as well as any STC region that is on Twitter. We also follow any customers that we know have Twitter accounts.

Several of the WebWorks staff have personal Twitter accounts. The two most active are:

Me — I tend to post on my STC related activities, and my freelance writing projects.

Jennifer Whitley — Jen posts a lot about social media; she is also a pilot and posts a lot about flying.

There are several other people at WebWorks on Twitter, including the CEO and Support Staff, but as yet they aren’t as active.

OK, so how do we use Twitter as part of our documentation strategy?

Currently we use an RSS feed from Twitter search to be notified of anyone asking questions about the product. When that happens, we respond by Twitter giving them a link to either our documentation wiki or our Help Center wiki as needed.

We tweet about updates and new topics added to the wikis on Twitter.

We tweet about technical blog posts. By the way, we just launched a new blog site at http://blogs.webworks.com.

We are considering doing some prototype work on the following:

Integrating the Twitter feed directly into the documentation wiki based on hashtags and RSS.

Having recent changes to the wikis automatically generate a Tweet.

Have the WebWorks Twitter account feed directly into the product online help for instances where the install is connected to the internet.

As I said these three are just conceptual ideas at the moment, and we are doing some experimental work around them. I’m also talking to a couple of other companies that are looking at integrating Twitter (or social media in general) with their corporate publishing strategy.

I’m impressed at the extent that WebWorks incorporates Twitter into their work, especially their use of hashtags to identify different areas of their documentation.

I was about to post Alan’s response when I saw a tweet from Dan Maurer, a technical writer in a rhetoric and professional writing program, saying he might write a masters thesis on Twitter and technical communication. I asked Dan what he thought of WebWorks’ use of Twitter.

Dan thinks Webworks’ use of Twitter focuses on the user, which is a good thing. And services that send Twitter direct messages when a wiki entry is updated are useful, especially for people who prefer this type of communication.

However, Dan fears that this is “just another method of getting word out to the user. A new way, and one that’s useful, but not really different from an e-mail list, blog, or RSS feed.”

So exactly what is the value of Twitter, in contrast to other means of communication? What unique quality does Twitter bring to the table? Dan lists three unique characteristics of Twitter communication:

Low attention threshold. (140 characters)

Mobile capability.

Networking. Our @ conversations are public … that’s how I find new people to follow.

But if given the option to subscribe to Twitter, RSS, or email to stay updated about a product, Dan says he would choose RSS, because it keeps his inbox free. “I use Twitter for conversations with interesting people, not to learn about the newest gadgets. Again, that’s what RSS is for,” he says.

I agree with much of Dan’s analysis. If one technology already fulfills a need, there’s little value in duplicating it with another technology. However, given the increasing amount of information we must sort through daily, the limitation of 140 characters per message is appealing.

Too Connected – Utopias and Dystopias of Communication

Tom Johnson — Tue, 19 Aug 2008 05:42:09 +0000

Some people feel that the ability to connect with anyone, anywhere, anytime is one of the utopias the Internet brings. For any question you have, the answer is a keystroke away. Google leads you to the site or person who can help. Country walls are irrelevant in the reach of information. You can connect with people in Malaysia, Australia, or Zimbabwe as if they lived next door. With this connectedness, all the silos and walled gardens tend to crumble as people, once strangers, connect and communicate with each other in milliseconds.

Last week while walking past Temple Square my friend John, a product manager where I work, painted a very different picture of connectedness. John asked me about Twitter, and as I was explaining it, Twitter seemed liked just another of the dozens of social media site out there.

“People always talk about how great it is,” John said, “that new media allows you to communicate and connect with each other, but that’s exactly what I don’t want. I don’t want all these people I don’t know emailing me and pinging me through Twitter, and Plurk and Linkedin and so on. I don’t see why anyone would want that.”

Too much communication becomes like noise and leads to a dystopia of connectedness

As we walked, I started to wonder why I myself would want it. Each day I’m bombarded with enough information to bury me. Email, tweets, instant messages, phone calls, SMS, blog comments, trackbacks, pingbacks, spam, newsletters, invitations to LinkedIn, Pulse, Plaxo, RSS feeds — it all gets to be like noise. Communication noise.

In my inbox now, I have 784+ unread messages. Most I’ve never opened because they aren’t … anything. In my RSS feeds, Google Reader constantly tells me I have 1,000+ unread posts. The comments on my blog pour day after day, whether I write new posts or not.

Sometimes the communication noise is even louder. Last week an anonymous lady called me at dinnertime to ask how to convert her WordPress.com site into a shopping cart to sell her art. Then “Sam” from New York (no idea who he is) called to say he’d followed my instructions on adding WordPress photo galleries with lightboxes but could not get it to work. He went on and on as if we were old friends.

(By the way, I now no longer answering my phone to see who it is.)

The more you blog, the more people you attract through Google. The more search-engine-optimized your posts are, the more people find you. The more tweets you send, the more people follow you. The more social networks you join, the more people add themselves to your page. The better posts you write, the more people subscribe to your RSS feed. The more content you generate – in whatever form and media – the more trackbacks and links people generate about you. The more you produce, the more emails and questions you get. You become like a content cloud – attracting Google searches.

Last week my kids pulled out an old home movie taken about 5 years ago — before we were all sucked into the Internet and Web 2.0. We seemed to have all the time in the world: sitting on a couch, or on a picnic table outside. (Yes, outside! in the sun, surrounded by …. nature, and grass! Haven’t seen that in a while.) On the video we smiled and laughed. Time moved much more slowly. No one was checking his BlackBerry, or posting to Twitter, or staying up late to blog. No feelings of concern about email. This was before the Web 2.0 deluge, before we received 100+ emails/comments/feeds/tweets a day. It seemed back then life was so different — before connectedness enveloped me like a fish net.

If connectedness is such a dystopia, why not just cut the wire, or unplug the cable? No one forces me to stay online. If the game is getting boring, no one’s preventing me from going home before the final buzzer.

Truthfully, I am somewhat addicted to connecteness. While 75% of it all is meaningless noise, there are some contexts that become extremely meaningful. Having a public space to write and publish my thoughts — where people actually read what I write and respond with comments or email or trackbacks — it’s motivating. My words no longer live solely in Word documents on an old hard drive, intended to be published in an obscure literary journal after months of slush pile dormancy. My writing freely propagates around the Internet. It freely connects with others. (No doubt for some, I am communication noise.)

Overall, to have a space to write and publish, to wake up the next morning and see half a dozen new comments on a post, to throw out a Tweet in a moment of total consternation at the grocery store, to read meaningful insights from others about topics I’m interested in — whether from social networks, RSS feeds, blogs, comments, listservs, or Twitter – it gets my mental wheels turning. The network cables are already too deep and intertwined to unplug them from my nervous system.

Nonetheless, I admit that I am conflicted. My oldest daughter is seven. She has her own blog. Should I encourage her to post more, and respond to comments from Heather, her little seven-year old friend (who also has a blog, and whom she has met once in Arizona)? Or should I encourage her to play outside, enjoying her offline childhood?

It’s not entirely an either/or scenario, but I’ll let her define her own paths in or around Web 2.0.

———

photo from Flickr