Welcome to summer reruns, part 1

My blog and I are taking it a little easier towards the end of the summer.

I’ve had a wonderful time with this blog so far, and I thank each and every one of you for reading, lurking or commenting. I’ve learned a lot from your comments, and I appreciate your support! It’s been a walk on the beach… 🙂

As we’re gearing up for the new season, here are some reruns from the last year or so.

Popular posts from my blog

Trends in technical communication 2010

This is one of my two most popular posts by far. With the help of several readers, we’re commenting on and discussing two trends from a Scriptorium webinar “Technical Commmunication Trends for 2010 and Beyond”. Sarah O’Keefe predicts that it will include content curation. And Ellis Pratt proposes that technical communications will soon also shape an emotional user experience. Incidentally, Ellis will speak on the same topic at TCUK, so go see him, if you have a chance!

Making it as a lone writer

This is the first post in a small series where I share lessons learned and best practices how lone writers can get ahead. Incidentally, I will speak on the same topic at TCUK, so come see me, if you have a chance!

Reading outside the tech writing box

I’ve found that reading helps my writing, even off-topic reading. Technology journalism works especially well for me. I share my favorite magazines and anthologies and link to five articles that you can read online.

Noteworthy posts from elsewhere

Speaking of reading around. If you want to read up on neighboring disciplines, I recommend these three excellent posts:

Complete Beginner’s Guide to Content Strategy

Complete Beginner’s Guide to Information Architecture

Standardized Approaches to Usability

Advertisement

Are you asking questions right?

Asking questions right (as in: correctly, appropriately) is more difficult and just as important as asking the right questions.

This is not about asking the right questions – with a little trainning and practice, we tech writers usually know how to do it. I find it much harder to ask the right questions right. I take my cue from Bertrand Russell who (allegedly) said:

The greatest challenge to any thinker is stating the problem in a way that will allow a solution.

(Photograph from Wikipedia.)

I think this is a pertinent issue for technical communicators in several ways:

• It’s our job, essentially. Any customer can state countless questions and problems he or she wants to solve with our product. And any developer or engineer can tell us how the product works. It’s our job to connect the two: To restate the customers’ problems – and to answer them – in a way customers find helpful.
• It helps us get useful answers from developers and engineers. Some of the best developers I’ve worked with always kept me on my toes: They would carefully consider my question and then answer it exactly. On the other hand, they would get easily impatient if I came up with a loose question such as “what is this new feature here?”
• It helps us get constructive feedback from reviewers and SMEs. Asking a reviewer whether “this is good documentation” may not get you very good review comments. For a much better way to state the problem, see Craig Haiss’ post about “Turning document reviews around quickly“. For example, he advises to “clearly indicate any questions that you have for the reviewers”. To allow for an easy and efficient solution, he also recommends  “that reviewers can agree to review deadlines beforehand” and to “use a signoff slip”.
• It helps us get support from management. This is probably the most difficult application of the quote. It requires not so much careful phrasing, but also evaluation and judgment of the problem at hand. This doesn’t mean we do the manager’s job. After all, the quote is not about finding a solution, but about allowing a solution. For example, I once had a scheduling conflict and asked my manager whether we could postpone delivery of one of the manuals. Instead, he negotiated to change one deliverable from a manual to a quick start guide, with a manual to be supplied later.

What strategies do you employ to communicate problems to colleagues and managers? Feel free to leave a comment!

What tech writers can learn from UX designers

We tech writers have a lot in common with user experience designers, really!

Even though we may step on each others turf occasionally, we share a common objective: Make customers and users successful with our products. Add the fact that our jobs combine creative challenges with restricted resources, our situations are structurally so similar that we can learn a lot from each other.

So if we technical communicators are serious about overcoming departmental silos with our contents, we should also pick up a few tricks from the guys and gals in the next room or cubicle…

Here are just some a few lessons I’ve learned from blogging UX designers that speak to us technical communicators as well. Incidentally, they are strategic and processual, but I’m sure we can also learn from their specific methods:

Doing stuff you weren’t hired to do? Keith LaFerriere’s “Why Did You Hire Me?” has some advice for you. It easily applies to technical writers who find themselves writing for marketing or editing and polishing anything from offers for sales to presentations for the exexcutive board. (All of these are fine, respectable tasks – but maybe they’re not what you excel at or where you see yourself going…)

Countering less than brilliant ideas which managers or customers may have about your work is the topic of Whitney Hess in “No One Nos: Learning to Say No to Bad Ideas“: “It is my job to put an end to bad design practices within an organization before I can make any progress on improving the lives of our customers.” Replace “design” with “documentation”, and you have yourself a mission. Whitney uses best practices and data to make her case and also shows just how to say “no”.

Winning your manager’s support to implement a new method, such as topic-based authoring, is essential, but difficult. Especially if the cost-benefit argument unexpectedly fails. In “Selling Usability to Your Manager“, David Travis recommends a more psychological approach to present salient benefits beyond the bottom line.

Getting buy-in for better processes across your company is the subject of a virtual panel discussion “Evangelizing UX Across an Entire Organization” written up by Janet M. Six. Designers and information architects weigh in with helpful advice, such as:

• “For different groups to embrace [it], those groups need to see the value in the process — not only for the organization as a whole, but for their particular role and discipline.”
• “Practitioners should reframe the issue by asking managers to support and enhance the ongoing satisfaction of the customer experience.”
• “The one clear finding that has come out of the entire UX movement is that focusing on your customers is the surest, most direct way for any company to make money.”

Realigning can be a good alternative to redesigning, as Cameron Moll explains in “Good Designers Redesign, Great Designers Realign“. The “Incessant Redesign” seems to afflict designers more often than technical communicators. Still, his basic idea also applies to documentation: “The desire to redesign is aesthetic-driven, while the desire to realign is purpose-driven.” There’s a place for either type of project; Cameron’s post helps you to make the right decision.

– What alliances with other departments have you found helpful? What methods and tricks have you learned from colleagues in design, training, customer support, etc.? Feel free to leave a comment!

Choosing the Right Tools

Choosing the right tools is obviously important – but also hard, when recommendations emphasize unique selling points that make comparisons difficult.

My fellow German Marc Achtelig has put together three pages with criteria to help you choose the tool that does what you need:

• Choosing a Help Authoring Tool
• Choosing a Screen Capture Tool
• Choosing a Screencasting Tool

The pages are very thorough and well thought out, but they don’t connect directly to products. As such, they’re great to help you make up your mind before you consult the pages of useful tools on his indoition web site. Or you can consult the HAT matrix and plug in all the features you’ve decided you need.

Marc also has a documentation quality check list which covers similar grounds (though shorter than a book can) as Gretchen Hargis, et al. in their book Developing Quality Technical Information.

As a bonus, all the information Marc has collected can be downloaded as a 100-page PDF.

How and why to estimate writing efforts

Estimating your writing efforts and deadlines is difficult, but essential.

Can you reliably estimate the time you need to write documentation? And the date when you can deliver? It often seems a daunting task because it depends on many external factors:

• The quality of specifications and designs.
• The availability of the finished product.
• The accessibility of subject-matter experts.
• The punctuality and diligence of reviewers.

It also seems futile to spend time estimating efforts when you know you don’t have enough time anyway. But even though it’s difficult and takes time, I recommend that you do it.

Why estimate?

If you don’t do it, someone else will make assumptions about your schedule. Even if you’re just left with the ever decreasing time between delayed development and scheduled shipment.

Estimating makes documentation accountable, in both senses of the word:

• You can explain the time you will spend on documentation. So it allows you to plan and budget the time. Share the estimates with your manager, and you can also share responsibility for the efforts.
• You can also be held accountable for the time you have spent. With estimates, you only will have to justify the specific difference that you ran over the plan. That’s much better than arguing about the complete time which may “seem kind of long” to your manager, though you know “that’s just how long documentation takes”…

Estimating makes documentation more transparent, in other words. It gives you and other stakeholders specific numbers to talk about ahead of time. It gives everybody more control over the documentation process.

For example, I once faced the complaint from product managers that documentation held everything up, that we could ship sooner, if only the tech writer got his act together. By introducing estimates and refining the reporting, I was able to show that it was specifically the reviewers which held up the process. Everybody took the estimated time, more or less, but reviewers delayed their tasks unduly. In fact, one late reviewer was a product manager who had voiced the complaint…

What to estimate?

You get what you measure and estimate. Or in the words of Tom DeMarco: “You can’t control what you can’t measure.”

If you estimate number of pages per day, you’ll get reams of paper. But that doesn’t guarantee that the documentation is useful and/or accurate.

If you count the number of features, options and buttons and base your estimate on that, you’ll get a thorough description of the user interface. And a customer who says, “Don’t tell me how it works, tell me how to use it.”

Apply task-oriented writing and estimate topics, instead:

1. Look at the specifications and designs to understand what’s being developed or produced from a user’s point of view.
2. Distill or translate what you find:
   • Identify modular concepts that users will need to know. A microwave convection combination oven can use descriptions of both concepts with their principles and different use cases.
   • Sketch out user workflows to set up and operate the product and break them down into individual procedures. That oven’s manual will probably have procedures to set it up, to thaw frozen food, to heat food (using the microwave), to bake stuff (using the convection), and to clean it.

A high-level view of the topics and their complexity allows you to make a rough estimate how long you’ll need to create useful topic-based documentation.

How to estimate?

Estimate efficiently. I once estimated a one-month project so well, I was off by two hours in the end. The problem was that it took me two days to crunch all the numbers… I can’t recommend that.

So don’t try to be 100% accurate in your estimate, if it takes you a long time to do it. Here are a few ideas to spend less time on estimates:

• Look at past efforts: Most likely, you’ll do some reporting anyway. Use this as the basis for future estimates. Maybe you’ll find an average time you take to write a concept topic. And one time period for easy and short procedures and another for more complex ones.
• Refine your estimates and average sizes over time: No need to get it perfectly right the first time, especially, if you start estimations on your own account. Try to run the numbers beneath the radar before you come forth with them.
• Trust the law of averages: What extra time you need for one topic, you’ll probably save on another.
• Trust your experience: After a while, you won’t need to sketch out individual topics. You’ll be able to take an adequate measure from looking through the spec or design.

Further reading

To learn more, check out:

• Donald LeVie’s Intercom article “Documentation Metrics”, available via EServer
• Steven Jong’s STC paper “Measuring Quality”, available as PDF
• Gretchen Hargis, et al., “Task-Oriented Writing for Techies“
• Wikipedia on software metrics which has the Tom DeMarco quote

Your turn

Do you estimate your efforts ahead of time? Is it worth the extra effort? How do you use the numbers to your advantage? Please leave a comment.

Buy yourself time as a lone writer, part 2

To be “making it as a lone writer“, you need time. Time to develop your skills, improve the documentation, reach out and network with other teams.

Last week, I talked about some strategies to buy yourself time. You can, for example, move to(wards) topic-based authoring. This eliminates internal inefficiencies, namely those you can deal with yourself.

To buy yourself time, you can also try to:

Fight external inefficiencies

These are inefficiencies that encroach on you from other teams and give you a hard time. Here are two common examples:

Don’t test the product when you should be documenting it. It’s late in the production cycle, and you’re already looking at a tight schedule. You really have to start documenting now to ship on time. And then you find bugs and inconsistencies in the product and interface all over the place…

Testing as a lone writer is not a bad thing as such. Often, it’s what makes the job so interesting and diverse. The problem is if the time isn’t budgeted. Make sure such time and efforts are accounted for. If you enjoy testing, make sure your manager knows you’re doing it, and that it you need extra time for it.

If you cannot test efficiently, or if it’s actually someone else’s job, try not to do it. Yes, “we’re all in this together, and we have to cover each other’s backs”, but that shouldn’t mean that you pick up all the loose ends, just because you’re last in line. Being in it together doesn’t mean taking it out on the lone writer.

Time and again, I’ve “given back” products for testing along with a list of 19 bugs I’ve found in the first hour of documenting. Most managers actually understand that I cannot write documentation efficiently on unfinished or buggy products. To fix this problem, you might need to address a larger issue:

Insist that documentation is included in the project plan. Often, lone writers drop off the radar, and their efforts are not planned appropriately in the project plan or the production schedule. It should be, of course. Your manager and your project managers might not like to hear it, but good documentation takes an adequate amount of time. If they don’t believe you, let them compare measly quick starts that can be thrown together in two days with tutorials or manuals that might take two weeks or longer.

Lone writers are often not used to stand up for their documentation like this. Still, I’ve found it well worth the effort: You can start small by simply inquiring about the project schedule. Maybe you’ve heard about a strategic project or an important customer, and you want to make sure you can deliver good documentation along with it. It shows you’re taking an interest in the project as a whole and your position in it. Managers can’t push you away so easily, once they’ve understood your engagement will help their project – even if it means budgeting extra time.

Usually, project managers have pain points that you can appeal to: Maybe a certain level of documentation is part of the requirements, so it should be planned like any other part of the product? Maybe they’ll latch on to better documentation to buy themselves time and appease the customer? (They can’t very well say they need the extra time also for last-minute development and testing…)

Your turn

What other inefficiencies steal your time and energy? How do you cope with them? Feel free to leave a comment.