TCUK10 conference videos online

Speaking of conferences, one stream of 13 presentations at the ISTC’s conference TCUK10 was recorded, and the videos are now online.

Included are the two keynotes by Nokia’s David Black and by J Haynes of Haynes manuals, as well as Roger Hart on content strategy, Chris Atherton on the psychology of usability, and many more.

The slide from J Haynes’ presentation is both, a sign and a reason of Haynes’ success. Check out the presentation to hear the story behind it.

(My own presentation wasn’t recorded, and I like to believe it’s for the better… 🙂 )


Happy holidays & a recommended read

Kai’s Tech Writing Blog takes a break for the rest of the year. I wish you a happy holiday season, and I’ll see you in early 2011.

Cover of Paul Harding's book TinkersIf you’re looking for a change of pace, I can recommend a great, but short book: Paul Harding’s Pulitzer Prize-winning novel Tinkers makes for slow wonderful reading as the main character thinks back on his and his father’s life in rural New England through the 20th century.

Interspersed with the narrative are excerpts from the Rev. Kenner Davenport’s The Reasonable Horologist from 1783. This instructional text is a great example for artful and stylish documentation:

Now, the horologist looks upon an openfaced, fairy-book contraption; gears lean to and fro like a lazy machine in a dream. The universe’s time cannot be marked thusly. Such a crooked and flimsy device could only keep the fantastic hours of unruly ghosts. The front plate of the works is taken in hand and fitted first onto the upfacing arbors of the main and strike springs, these being the largest and most easily fitted of the sundry parts. This accomplished, the horologist then lifts the rickety sandwich of loose guts to eye level, holding the works approximately together by squeezing the two plates, taking care to apply neither too much pressure (thus damaging the finer of the unaligned arbor ends) nor too little (thus causing the half-re-formed machine to disassemble itself back into its various constituent parts, which often flee to dusty and obscure nooks throughout the horologist’s workshop, causing much profaning and blasphemy).

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:

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?

Cranking widgets: “Getting Things Done” (GTD) as a tech writer

“Getting Things Done”, David Allen’s productivity method, works well for a technical writer who’s lined up tasks, so they’re ready to go and as easy as cranking widgets. Here’s how in my #2 GTD Principle for Tech Writers. (My #1 principle is about universal capture.)

Cranking widgets

Most of us technical writers face two different types of tasks: Deciding what to do – and actually doing it. It’s the second part that David Allen calls “cranking widgets”. It sounds like a mindless activity, but I take it to mean to get down to our craft and actually write. (For a more GTD-like take, try zenhabits’ recipe…)

I believe, and have experienced, that it makes sense to distinguish and to separate those two types of tasks as soon as a task appears. That gives me a slim chance that I’ll even have the time to decide before I actually have to do it.

The benefit is that I get to group similar tasks together and do related work at once, so I don’t have to jump around in the documentation with every single task I get.

The challenge is to juggle the deciding and the doing. Often I don’t have the time to do all the deciding until my inbox is empty and all tasks are neatly laid out and ready to be done.

Deciding before doing

This kind of task often comes disguised as the second type:

  • I get a phone call that asks me to correct something in existing documentation.
  • I receive an email about something that hasn’t been documented yet.
  • I get a request to furnish screenshots for a localized manual.

All these things need to be done eventually. But for efficient and effective documentation, it makes sense to first decide what to do exactly:

  • Is the correction in existing documentation actually legitimate? And if so, when is the best time to do it?
  • Is the missing documentation actually missing, or overdue from the latest release, or really part of a future release? Again, when is the best time to write and provide it?
  • What’s the most efficient way to get the screenshots for localization? Do I have to do those, or can I ask an intern to do them? If I should do them, should I change my process and create them along with the ones in the source language?

How to decide

The reason to keep the deciding apart from the doing is that the first engages me in a very different way. Deciding what to do is mainly thinking, planning and organizing: Is a request legitimate and timely? What do I need to do that? When is the best time to do it? This part is mainly concerned with logistics.

My answer is usually one of those four decisions:

  1. Do it now. This is what I choose for tasks that simply cannot wait and for tasks which don’t take very long. In other words, tasks which get much bigger by looking and deciding a couple of times. The risk is that these tasks take up much of my daily time, but the reward is that they’re in and out fairly quickly.
  2. Defer it to a set deadline. This goes for all requests that come with a deadline, whether it’s explicit or implied, for example, because it’s connected to an upcoming version or release of the documentation. These tasks go onto my to-do-list. You can also put them into your calendar or project plan…
  3. Defer it to sometime later. This is for everything that’s currently out of scope or merely nice to have. It goes on to a wish list.
  4. Delegate it. This is frequently wishful thinking, because most of the time I don’t have anyone to delegate to… 🙂 But occasionally, I get lucky and can ask an intern to take those screenshots… After I delegate the task, I’ll have to make sure to follow up, especially when it’s got a deadline.

Doing after deciding

Once I have sorted out (hopefully most of) my tasks, I can set about doing them, starting with the most urgent ones, but taking all the related ones together. I’m cranking widgets and, if I’m lucky, I might get into the flow.

Your turn

Does arranging your tasks work for you? Or do you have your work arranged for you? Or do you simply not have the time to even bother? Feel free to leave a comment.

Capture everything, or: Are you “Getting Things Done”?

Of course you are getting things done – like most of us tech writers… But do you apply the David Allen’s GTD method from his book Getting Things Done: The Art of Stress-Free Productivity (GTD)? (Hence the quotes into the title…)

Over the years, I’ve found a few principles from Allen’s method especially valuable for tech writers, whether you are a manager or not. They can also be found in other productivity contexts. I’m describing them as parts of GTD, because it’s a well-known method that explains its principles well – even if the implementation can be cumbersome. But that’s what Zen to Done is for… 🙂

Today, I discuss my #1 GTD Principle for Tech Writers:

Universal capture

The idea of universal capture (aka ubiquitous capture), as I understand it, is this: You’re most productive when you concentrate on the task at hand. You don’t waste “brain cycles” remembering other task. To free your mind from all this remembering, you dump everything into a consistent, trusted system – your universal capture. I find this blatantly obvious – and difficult to do well and reliably.

The problem

As I update documentation, new features need to be described in release notes, one or several manuals and the online help. At the same time, the occasional gap or error needs to be fixed in manuals and/or online help. Due to time and system constraints, I cannot address each issue in all formats as soon as it pops up.

So I need a way to capture any and all issues reliably, so I can forget about them until it’s time to address them. At first, I tried to use my inbox by sorting issues into one sub-folder per format. This approach had several problems:

  • Some issues needed to be addressed in more than one format or more than one manual.
  • Some issues were thrown up in phone calls or when colleagues stopped by with a manual in their hand.

My solution

I’m now using a personal wiki in our intranet which is, for transparency reasons, open for everyone to see and edit. This page is quick and easy to access and edit. It makes few demands on structure and allows me to be as brief or as elabrate as I can be at the “capturing moment.”

Each deliverable has a section of its own, so I can have the same entry in several sections if necessary. When it’s time to update a deliverable, I know I’ll have all issues captured in my wiki list. As I work on it, I strike through each addressed issue. Around the publication date, I condense all issues into a summary of major updates.

More tips and tricks

Leo Babauta (creator of Zen to Done) shares a few general insights about how ubiquitous capture works and when it doesn’t.

Your turn

Do you use universal capture? Or another method of GTD? Do you find it useful? What tools do you use? Please feel free to comment!

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

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:

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.