Recommended read: Practice technical writing

Becoming a better tech writer requires practice.

Mike Pope, tech editor at Microsoft in Seattle, has a brilliant blog post about 12 ways to practice tech writing. The catch is he means “practice” like a musician, so you learn to do stuff better than yesterday – instead of just doing the same things over and over.

Over the last years, I’ve tried all 12 ways, and they’ve all helped me to become a better writer. And most of them can be fun, too, at least most of the time… 🙂

Here are just six of the ways as a teaser, but I highly recommend you head on over to Mike’s post to find out about all of them with details and examples.

1. Read other technical writing attentively.
2. Read about writing.
5. Writing something outside your usual material.
7. Edit someone else’s work.
10. Learn new tools and new ways to use your existing tools.
11. Talk to other writers.

Advertisements

Getting ahead as a lone author, the article

“Getting ahead as a lone author”, based on my presentation in last September’s TCUK conference, appeared as a 3.5-page article in the current Winter 2010 issue of ISTC’s Communicator.

Click the cover to download the article in PDF.

Click to download the article in PDF.

I’ve covered lone authors over the last months in blog posts and in my presentation, after which Katherine Judge, commissioning editor of ISTC’s quarterly, asked me to write it up as an article which I share with you today.

It’s a concise summary of my talk, along these headings:

  • Overcome benign neglect
  • Buy yourself time
    • Implement topic-based authoring
    • Don’t test when you should be documenting
    • Learn to say ‘later’ and ‘no’
    • Control interruptions
  • Treat documentation as a business
    • Make documentation an asset
    • Estimate documentation effort
    • Plan documentation properly
    • Embrace reporting and metrics

2011 megatrend in technical communications

I think this year’s megatrend for technical communicators and their managers, especially employed ones, is to position tech comm as a business in its own right – or to be redundant in the long run.

This is my conclusion after thinking about three astute predictions that Sarah O’Keefe recently blogged about.

– I know: I’m late to the predictions party. And I’m actually not very good at crystal ball gazing. I’m much better at reconfiguring what I find. So my contributions are comments and some additional reasons why I think Sarah’s right.

Three sides of the same coin

If you’ve read Sarah’s post, I’ll just remind you of the headings of her predictions:

  • A schism in tech comm (traditional vs. modern tech comm)
  • The age of accountability
  • Increased focus on business value

If that doesn’t ring a bell, head on over and read her post, I’ll wait… 🙂

I think Sarah’s predictions are really three sides (?) of the same coin. And I’d be surprised to see a documentation team experience only one of them.

Business value

The lackluster attitude about documentation of “No one reads it, but you gotta have it” has been widely replaced by close scrutiny of its value add and ROI. I’ve recently seen a doc team’s initiative that had to present the same business case, including cost saved and break even, as any other internal initiative that wanted to spend some money. But more is at stake for us writers than playing the numbers game with managers and bean counters.

The question is how the tech comm team is perceived: As a cost center or as contributing to the corporate assets. The latter is of course more desirable and can only succeed when we break down departmental silos, when collaborate with other teams and become user advocates, see my earlier comment on Scriptorium’s blog.

Now take a step back and think of what that cost vs. asset question means to your job and your career outlook. To me, it’s awfully close to being seen as part of the problem or part of the solution…

Another reason why I think tech writers do well to consider and promote their business value is…

Accountability

Sarah’s second prediction follows directly from attention to business value: Once a company expects ROI from documentation, it will want to monitor the output. And that means to hold the documentation team accountable, not by measuring the quantity of produced stuff, but by measuring the quality of useful assets that have been efficiently produced. (It’ s worth keeping in mind the difference between accountability and responsibility; link courtesy of Jurgen Appelo and his presentation on authority and delegation.)

In the metrics, you may have some leverage: If you’ve ever tried it, you’ll find it’s awfully hard to come up with reliable metrics for documentation quality. The good news is that your managers will usually find it even harder. That’s a chance for you to apply some “Top strategies to embrace cost metrics” .

If you’re alert and on top of your game, you’ll find you have some agency in how you’re measured. It won’t always be your choice alone, but to a certain extent, you can choose sides in…

The schism in tech communication

The distinction looks crude, but I’ve found that many technical writers fall into one of the two camps that Sarah has identified:

  • “Traditional tech writers” who produce communication deliverables, such as user manuals and online help.
  • “Modern tech communicators” who provide user assistance services as part of the customer experience.

Note that this distinction has nothing to do with quality! I know very diligent, highly qualified people in both groups, and I’ve seen sloppy work in conventional manuals and modern screencasts.

I believe how that schism plays out for each writer in a team has a lot to do with the accountability of the documentation team, the responsibility of the team members and the dynamics between the members: Ideally, both types complement each other – and can show management that they are strong and agile because of their complementary strengths.

Now what?

Okay, so treating your documentation as a business before everybody else does sounds reasonable. For specific next steps, may I recommend the slides from my TCUK presentation “Getting ahead as a lone writer” and my other blog posts for lone writers. Even if you’re not a lone writer, you’ll find many ideas also apply to documentation teams.

Your turn

What do you think? Are these trends part of a larger movement to economize and commodify technical writing? Or is it nothing new, not worth beating a dead horse over? Please leave a comment.

Resolution for 2011: Attend a conference!

Attending a conference is the perfect professional new year’s resolution for us tech writers: Regardless of what other plans for improvement you (or your boss) have, tech comm conferences are the perfect platform to exchange ideas, learn about new methods and tools and generally recharge your enthusiasm!

If you’re a manager: Sending your tech writer to a conference is one of the easiest and best ways to motivate her or him and to ensure that your documentation is in step with trends and developments! See my previous posts about conferences for insights and raves.

Alan Houser at tekom 2010

(Alan Houser at tekom 2010, photo by jophan).

To start you off, here are some of the pivotal conferences in the US and in Europe – with one “write-in” conference in Israel added by commenters. The list had great help from Linda Urban who suggested most of the events in response to a twitter query. Thank you, Linda!

The list is sorted by date; the quotations are taken from the event web sites. If you have any advice about events listed or missing, help us all out and leave a comment below.

MEGAComm

February, 20; Ramat Gan (Tel Aviv), Israel

MEGAComm combines two related communities, technical communicators and MARCOM professionals, offering sessions and networking opportunities for both.

WritersUA

March, 13-16; Long Beach (Los Angeles), CA, USA

Developing the best possible user experience for all types of software applications through well-designed interfaces and helpful and accessible support information

CMS/DITA

April, 4-6; Baltimore, MD, USA

Content management and DITA in four conference segments: Management, information design and development, technical solutions, and tools and technology

STC Summit

May, 15-18; Sacramento, CA, USA

More than 80 sessions covering all aspects of technical writing, editing, project management, and publication production

Congility

May, 24-26; Gatwick (London), UK

Content Integration: Leveraging Content Standards to Improve Customer Experience; reducing cost of content and translation; implementing XML, DITA, reuse and dynamic publishing; applying content standards and best practices

UA Europe

June, 16-17; Brighton, UK

Latest industry trends, technical developments, and best practice in software user assistance and online help

CS Forum

September, 05-07; London, UK

Talks and interactive workshops for content strategists, web editors, user experience designers, technical writers, CMS developers

Technical Communication UK

September, 20-22; Oxford, UK

Technical Communication UK is the annual conference that aims to meet the needs of technical communicators, their managers and clients, from every corner of the industry.

tekom

October, 18-20; Wiesbaden, DE

Nearly 200 lectures, workshops, tutorials, and discussion groups on latest developments in technical communication and documentation

DITA Europe

November 7-8, Prague, CZ
Technical writers, IT professionals, information architects, publications managers meet publications professionals who have implemented DITA in their organizations and hear from representatives of key tools vendors who are actively supporting the DITA community.

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.

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! 🙂

 

Getting ahead as a lone author, my TCUK presentation

I’ve just held my first presentation at a technical writing conference: On September 22, I spoke about “Getting ahead as a lone author” at the ISTC’s conference “Technical Communication UK” near Oxford.

If you’ve been following this blog, you will recognize the theme: I’ve covered several angles of this topic throughout the year. My presentation was basically a condensed version of many of the ideas on this blog, neatly wrapped into 5 best practices, and with the opportunity to ask questions or to comment.

I was glad to have the first slot after the opening keynote, so I could get my presentation out of the way: As much as I was looking forward to it, it did interfere with my attention and general enjoyment, as I kept thinking about whether it was too long or not appropriate in some way.

The opening keynote then set a very comfortable tone: The topic was serious, yet delivered with an ironic sense of humor. “Yeah,” I thought, “I can follow this…”

I counted 23 people in my audience – not a lot in a conference of 180, but it suited me just fine. While my pacing was brisk, I think, it was still easy to follow and engaging.

I finished after 30 minutes to leave 10 minutes for questions and answers. After all, I can’t claim to have any more experience or any better answers than any other lone author. Most of the questions asked for clarifications or further explanations and showed that many lone authors have similar concerns.

As I’ve found out from the comments, one of the weaknesses of the presentation was that I didn’t make all of my assumptions clear. For example, someone helpfully pointed out that authors in a (well-defined) agile programming environment don’t have many of the problems of authors in a waterfall project model as I described it.

On the whole, it was a very valuable experience: I now know I can hold a presentation and get a point across to a room full of fellow tech writers. And I hope to do it again someday.

I had some help on the way: I thank Linda Urban for first suggesting that I could do this. And Karen Mardahl for keeping me pointed in the right direction when I was getting nervous the evening before.

If you have something you are passionate about in your job, I can only encourage you to “get it out”. Write an article, start a blog or hold a presentation at a conference. Chances are it will mean something to your colleagues, either because they are concerned with the same topic or infected by your enthusiasm. And don’t be afraid to seek out help, none of us has been born an author or a presenter, and you’ll find many people willing to help you along.

Resources

  • My presentation slides: You can see and download my slides which have been enriched to link to blog posts and web sites with more resources.
  • How to hold a presentation: There are a lot of web pages about this, these two have helped me to prepare and to make me confident that I didn’t forget anything.

If you have any feedback on the presentation, whether you attended it or not, I’d be happy to hear it!