Shift your perspective and learn

We tech writers can learn a lot from neighboring disciplines and from people in other professions who address similar issues as we do.

Today, I recommend a couple of recent blog posts that speak to technical writers, too.

For each post, I’ll first point out what it’s about and then explain why I find it relevant for technical communications.

So join me: Let’s shift our perspective and think outside the box for a moment. 🙂

3 Ways Document Collaboration is Becoming More Social

Joe Shepley predicts on CMSWire how writing and maintaining documents will change over the next two years or so. He’s not talking about tech comm documentation, but business documents in general. They will change as social collaboration tools help us flee the “clunky trinity of shared drives, hard drives and email”. In his words:

1. Some documents will no longer be documents at all
2. Some documents will no longer begin their lives as documents
3. Some documents will remain documents throughout their lifecycle, but how they get created and shared will change

– Of course, tech writers have been thinking for years now about formats other than documents, hence the discussions about wikis for documentation and about content strategy. I find Joe’s arguments relevant for these insights:

• Format should follow function. Choose the format that supports your content’s lifespan and frequency of change – and reader inclination, I would add for technical communications. Too often, I’ve had the format dictate how I write: I created Word documents, complete with title pages, table of contents and header and footer layout for internal communications. They would do just as well as wiki pages which are easier to create and modify, but still accountable thanks to history and rollback functions.
• Format can be fluid. The content needs to be reliable throughout the lifecycle, but the format can actually change. Tom Johnson explores this idea in more detail in his recent post Forum → Wiki → Blog Workflow.

Stakeholder interviews for quality content: Why, who, and how

Kathy Hanbury explains on the E3 Content Strategy blog how stakeholder interviews are important as you embark on implementing your content strategy. I’m summarizing those of her points that I find especially worthwhile:

• Interview stakeholders to establish credibility, to identify patterns and structures, and to find discrepancies and gaps
• Interview stakeholders who know the customers, the technology and the subject matter
• When you interview, be respectful of time, carefully craft your questions and take good notes

– For technical writers, interviewing developers or engineers, subject matter experts, as well as customers is an important skill. I appreciate Kathy’s post as a reminder of several points that I sometimes forget:

• Interviews are essential for quality and relevance of the documentation. And nothing can replace them, really, though customer surveys can come close if done well.
• Interviews are about covering all bases. Depending on organizational structure, tech writers have easy access to developers, engineers or whatever department they are assigned to. But documentation has stakeholders in other teams, too, for example in product management, customer service and training. Interviews can help you to ensure that your documentation is useful and balanced by addressing not only how the system works, but also how to use it efficiently and what it was designed to do.

Your turn

To learn more from neighboring disciplines, see my post about “What tech writers can learn from UX designers“.

If you have picked up insights or lessons from other disciplines, feel free to leave comment!

Advertisement

Top 10 reasons for tech writers and trainers to collaborate

Technical writers can and should collaborate with trainers to offer customers a unified and cost-effective learning experience. Here are eight specific reasons why they should collaborate – and two why they cannot afford not to do it:

1. Same goal: Ensure that customers can set up and operate the product efficiently, effectively and confidently.
2. Same audience:  Customers, more specifically users of the product (who, in a corporate setting, may have made the decision to use it or not).
3. Same demands by that audience: Fill a knowledge gap, whether it’s large or small, conceptual or practical.
4. Similar deliverables: Conceptual and instructional/procedural information, possibly in different formats, such as training slides or handouts, user manuals or online help.
5. Cost-effective deliverables: Share text and images, use cases and examples.
6. Better coverage: Writers and trainers see the product and its users from different angle and can help avoid professional myopia.
7. Beneficial reviews: Writers and trainers who review each others work also learn about their own deliverables.
8. Satisfied customers: A unified learning experience increases user confidence, satisfaction with and trust in the product.

Companies where writers do not collaborate with trainers run a considerable risk:

1. Confused customers: Incoherent or even contradicting messages in documentation and training materials confuse and alienate users.
2. Lost business, potentially in three ways:
   • Bad reputation and bad impressions keep prospects from buying.
   • Bad learning experience keeps customers from continuing or returning to the product.
   • If you’re really big, external companies can take a bite out of your training or manual business.  This is harder to replicate and hence less likely if you offer one seamless learning experience.

Your turn

Have you considered or tried to collaborate with training? Has it been worthwhile? Can this be a first practical step towards content strategy? Please leave a comment.

How a degree helps a technical writer

A college degree can help you in technical writing, though maybe not in the ways you expect.

How relevant is a college education for the field of technical communication? A couple of very good and influential tech writing blogs have recently discussed this issue:

• Why Tech Comm Is a Career Path of Last Resort for Students, by Tom Johnson, about an English department
• Rhetorical theory vs. tech comm reality, by Ryan Fulcher, Scriptorium, about a tech comm program

The question is both pertinent and impertinent, because Tom and Ryan frame it in a way that devalues college education [… at least in the specific program they are criticizing, see Ryan’s comment below. 18 Nov 2010]. Tom says tech comm “should not be taught in the context of an English department, because [it] is not understood or encouraged in traditional English curricula.” Ryan says he’s gained more useful knowledge in 5 months in the job than in his entire time in the tech comm MS program. I cannot argue with their experiences, and I cannot hope to convince them otherwise.

To help anyone with similar questions who’s in college now or has recently graduated, I can offer my own alternative assessment: How a college degree helped me become a passionate and, I dare say, good technical writer.

What I sought

Computer Science and Business as a combined major was how I started college. I sought to learn how to build software and how to run a business. What I got was learning by rote, too much how it’s done and not enough why and how it could be done better. I dropped the major after a semester.

I had embarked on rational and reasonable education and found that my heart wasn’t in it. I just couldn’t see myself spending several years getting a degree as a means to an end. I expected college to teach me something that was interesting in its own right, not a promise that I could apply it in a future job, or maybe not.

American Studies is what I declared as my major after two weeks of soul searching. That’s where I found my academic home. The curriculum was heavy on literature, social history and culture. The emphasis was on understanding what holds the USA and its culture together, to come to terms with its cultural and artistic developments, and to use whatever academic theories could be made useful.

Over ten years ago, I’ve received my M.A. in American Studies. I’m a technical writer by choice and practice, with the heart and the outlook of an Americanist.

What I learned

In American Studies, I learned a lot of things. Almost all of them do not directly relate to technical writing. Here are some things that I’ve found useful and applicable as a technical writer:

• How to write long, coherently argued, understandable papers in correct English. It took me a long time to get it right. It took me longer yet to realize the importance of tailoring my message and language to my audience. And it took me even longer to realize that all this combined is a rare and marketable skill.
• How to explain something that defies explanation to people who think they already know how it works. After you’ve ever tried to explain America to Germans who have it all figured out from movies and news media, writing user manuals is actually pretty easy. Most products I’ve dealt with are less complex than a country of 310 million people, even if you only regard the most recent 400 years.
• How to cope with complexity. Literary studies can appear pretty neat, especially when you deal with only one author or one book. Studying a country and its culture is a more daunting task, not least because the people carry on so, with no regard for your studies. Trying to keep your insights reconciled with an ever-changing reality is a good preparation for your survival in large corporate environments and their organisational quirks.
• How to organize to finish. Formulating a thesis and then framing and arguing it was part of my later assignments. That was a good preparation for writing user manuals from scratch. The “thesis” in that case is the easy part. The customer wants to do stuff with the product and look cool while doing it. But the rest is again up to the writer: Framing the text in a context of use, consulting all available sources, explaining it in the most understandable and most efficient way.
• A turn of phrase occasionally: That a question can be both pertinent and impertinent (see above) is something that I learned from Thoreau’s Walden, the second paragraph of the “Economy” chapter to be precise.

What I know now

A college education can work very well for you, if you take it for what it is and don’t expect something that it isn’t. Stanley Fish makes a very astute argument for what a university can be and do:

When it comes to justifying the humanities, the wrong questions are what benefits do you provide for society (I’m not denying there are some) and are you cost-effective. The right question is how do … your program of research and teaching fit into what we are supposed to be doing as a university.

It’s important to realize that this kind of education comes with no guarantee: It guarantees you neither a job, nor happiness, nor that you’ll always be right or make the right decisions.

But it gives you the tools to gather information, take responsibility and make the decisions that affect your life. In short, such an education can give you hope. In the words of Václav Havel, writer, dramatist, and the first President of the Czech Republic:

Hope … is not the conviction that something will turn out well, but the certainty that something makes sense, regardless of how it turns out.

Your turn

What did you get out of a college education? Was it useful for immediately applicable skills? Was it instrumental to become who you are? Or was it a waste of time?

Lone writer, meet the community network

As part of his excellent review series of the tekom conference, Jason Nichols comments on

the dichotomy between the single-author versus everyone-is-an-author scenario, and why technical communicators not only need to produce documentation, but facilitate the publishing of it from others.

Jason contrasts the reach and limits of a lone writer with the possibilities of a network such as SAP’s community. It’s an unlikely combination to be sure, but his argument about the changing scope of the (lone) writer’s environment are insightful.

I highly recommend this post, as well as his entire review series.

Top 4 steps to solicit perfect documentation reviews

To get the best possible reviews from subject matter experts (SMEs), we tech writers can prepare, make our expectations clear and help our reviewers excel at their job.

Soliciting documentation reviews from SMEs can be tricky: They are usually very busy, juggling dozens of tasks, while putting off several more. The last thing they need is a writer to waltz into their office making a demand on their time. Here’s what I do to get an SME to review a manual of 100 pages or 25,000 words. It doesn’t work always, but it’s worth a try – they are the experts after all… 🙂

1. Preparing

Before I even approach the SME, I prepare:

1. Find the ideal reviewer. This might be a colleague who’s installed and/or used the described product. At any rate, it should be someone who is very close to the customer and knows users’ needs and workflows. I also try to find out why the person is the best reviewer, for example, because of recent or in-depth experience with the product.
2. Get permission to ask. I ask the SME’s manager for permission first. This gives the manager a chance to intervene on the SME’s behalf or to suggest someone else – who’s hopefully as good or better. It also helps to deflect the SME’s attempt to defer me to the manager. But it’s not so I can tell the SME: “But your manager said for you to do it.” – I still have to ask and convince the SME!

2. “Save the date”

I ask the SME well ahead of time if she or he will do the review. I usually approach them in person, but it works as well over the phone or via e-mail. If it’s a talk, I follow up with a “save the date” e-mail as a reminder with the essential details. This contact is mainly about the why and the when, so we discuss the following:

• What to review in general and briefly what the manual is for, why or how it’s new, and what’s to review.
• Why the review is essential, namely to ensure we deliver the best possible product and make it easy and effective to use for our customers – and also for colleagues like the SME. This is a good time to show how our joint effort will benefit the customers and that the SME and I have one and the same goal.
• Why the SME is the best person to do the review.
• When to review and what leeway, if any, I have to accommodate the SME’s schedule.

3. “Please review”

At the ‘saved date’, I send the SME my “please review” e-mail with detailed review instructions. This is mainly about the what and the how, so I include:

• The deadline and to let me know asap if there’s a scheduling problem.
• What to review in detail. Usually, I ask the SME to review the complete manual. But sometimes that’s not necessary: Maybe you have several reviews which complement each other. Or maybe you’ve reused topics that don’t require a review.
• How to review. I’ve found that concise general guidelines work best for non-writers. So I tell SMEs to ensure that the manual is complete, correct and usable, and maybe illustrate each of these criteria with a question.
• How to give feedback. Personally, I don’t insist on any specific format, whether reviewers use tracked changes, comments in the margins or handwritten comments on printouts. But if you prefer on a format, let your reviewer know.

4. “Thank you”

After I’ve received and processed all the feedback, or when the manual has been published, I send a brief “thank you” e-mail to the reviewers. In it, I point out how the reviews improved the manual and what major changes I have made. It shows my reviewers that their input matters, it shows my gratitude, and it leaves a good impression for the next time that I need a review.

This works because…

… SMEs are experts who usually enjoy doing their job well. To benefit most from their expertise, give them a chance to do reviews well. So try to supply all the information and instructions they need.

Your turn

What recipes do you have to solicit reviews? How do you get buy-in from SMEs? Please leave a comment!

Two words every (lone) writer should know

Many technical writers, especially lone writers, wear many hats, and they like it that way. Some may proofread reports and marketing material, some may spruce up presentations, some may translate. It’s that variety that often makes a tech writer’s job more interesting. But it has two drawbacks that you might want to avoid if you want to heighten your profile and get recognized as a serious, responsible professional. Fortunately, each drawback can be deflected by a single word which you may want to add to your vocabulary.

Learn to say ‘later’

The first drawback is that you need to juggle very different deadlines. Often, these interesting extra tasks are small, but on short notice. Collect a lot of them, and they start to interfere with your long-term deadlines and your larger documentation tasks. If you negotiate deadlines for the smaller tasks, with your manager or directly with whoever requests them, you show responsibility and that you take the task seriously and don’t want to do it ‘on the side’. In other words, learn to say ‘later’.

Learn to say ‘no’

The second drawback is that lone writers often get defined by what they do – and it hurts them, if they are best known for their smaller, more visible tasks. If you’re the proofreader-in-residence or the person who edits reports to make them ‘nice by noon’, ask yourself if that is what adds the most value to your life and to the organisation. If it’s not, try to get rid of such tasks or at least limit them. Ditch the dirt that defines you. In other words, learn to say ‘no’.

Your turn

Have you added ‘later’ and  ‘no’ to your vocabulary? How successful have you been with them? Are the other words you recommend that tech writers should know and use? Leave a comment!

---

This post will appear in somewhat different format in the forthcoming Winter issue of ISTC’s Communicator. It will be my first publication in the field of technical communications, yippie! 🙂