Thursday, 27 January 2011
05:03 PM
I was recently ADD-ing my way through a series of links and ran across an essay by Steve Yegge in which he challenges programmers to practice their craft, "practice" here meaning the kind of practicing that musicians and basketball players do. The analogy with practicing an instrument is a good one, because he distinguishes ineffective practice — just repeating the same thing over and over — from effective practice in which you try to learn something you don't already know how to do. (Most people who can't seem to learn an instrument fail, I posit, because they are not taught how to practice effectively.[1]) Going to work and doing the same thing you did yesterday, last week, and all last year does not mean you are practicing your craft: you are not getting better at it.
I recommend that you read his essay, because he has insightful things to say about why you need to practice, and about things like the difference between smarts and skills, and "But I have a job already." (Altho like Yegge essays in general, it's not exactly a 60-second read.)
 Among his philosophical thoughts he lists a series of "practice drills." That got me thinking ... how would I apply that to technical writing? What sorts of "drills" would you do that would help you become a better technical writer?
There are probably a million ways. Here are a few that I thought of.
1. Read other technical writing attentively. You probably read other technical writing all the time, broadly defined — instructions, recipes, documentation for something you yourself are learning. Whenever you do, take a mental step back and think about what you're reading. Is it clear? Are there places where you're having difficulties? How is it organized? Are there parts you particularly like?
I'll emphasize that this can be writing about any field. If you knit, pay attention when you read about knitting; if you raise chickens, pay attention when you read about raising chickens; if you do photography ... etc. As I've noted before, I feel like I learned a lot about technical writing from "technical writing" I enjoyed, particularly How to Keep Your Volkswagen Alive and The Joy of Cooking (the Rombauer editions). Both books taught me an intrinsic approach to teaching via text: conceptual background, step-wise procedures, asides for points of interest or potential pitfalls. Of course, at the time I wasn't deliberately deconstructing those texts, but I do that all the time now — pretty much every time I read instructions, I think about what they've done and what I might learn from them.
Because I'm sort of a writing nerd, I go one further on this: when I find writing I really like, I often copy it out. It's a surprisingly effective way to really understand sentence-level structure. But I wouldn't expect most people to want to do that. :-)
2. Read about writing. The web is rich with information about writing: McIntyre, Freeman, Grammar Girl, Tom Johnson, as just a few examples from among many.
3. Write. Sort of a duh. An easy way to do this is to have a blog. It doesn't have to be about whatever technical field you normally work in, although to improve your technical writing specifically, you'd want to use the blog for some sort of technical writing. (If you normally write about software, for example, your blog can still be "technical writing" if write about quilting or cooking or motorcycles or whatever.)
If you blog, try to stick to a regular blogging cadence. (I know it's hard, look at me.) As with your normal work, writing to a deadline or schedule is a great motivator.
 4. Write for publication. Writing a blog is good for keeping the writing chops lubricated, but I've found that writing something for publication really, you know, focuses your attention. Perhaps it's the knowledge that some nameless, faceless editor someplace is going to give a thumbs up or thumbs down on what you write that makes it a very different experience (for me, anyway) from writing blog entries. And publications generally have quite specific requirements for subject and length and style. But that's why it's good practice — the guidelines mean you have to work a little harder.
5. Writing something outside your usual material. If you mostly write step-by-step procedures, try writing overviews or reference material, and vice versa (x2). Of course, many technical writers have to write everything, so they switch all the time between documentation types. The point is to practice a style of writing that isn't what you usually do, however that might be defined. Try writing street directions (see if you can improve on Mapquest, for example), or a recipe (find the least-competent cook you know and see if you can walk them through a recipe), or try creating a poster or a quick-start guide or a tutorial or cheat sheet or a video or a podcast for the material you usually work on but that lacks one of these things.
I hesitate to suggest it, but you might also consider writing something way, way out of the usual for technical writing. How about some limericks about your normal material? Haiku? Ever tried a sonnet? What this type of thing can do is make you have to think extremely hard about every word you're putting down, and forcing yourself to work within extremely tight constraints. Or sign yourself up for NaNoWriMo and spend November banging out a novel.
6. Get yourself edited. Unless you're in the luxurious position of having an editor for everything you write, find someone to review your writing. This doesn't have to be a professional editor, but try to find someone who can give you feedback on your writing. Ideally, what you want is someone who can give you not just a review of the text, but some solid tips for writing.
7. Edit someone else's work. This is a kind of fleshed-out version of an earlier point. Read someone else's work with the intent of giving them feedback. As you probably know, having to teach someone else is an excellent way to learn yourself.
8. Write a style guide. A style guide is really a way to capture and abstract a lot of thinking about writing. Like editing, it's a great exercise in paying attention to writing. If you do this for your regular work, you get invested in creating sensible and useful guidelines and then making yourself and other writers conform to it. (If you hand over enforcement of the style guide to someone else, this might be particularly true.)
9. Learn (or expand your knowledge of) the vocabulary of writing. You should really have a working grasp on grammar and usage rules (including punctuation). Any usage guide or even any semi-involved conversation about writing is going to throw around terms like "independent clause" and "passive" and "gerund" and so on. You should know parts of speech (nouns, verbs, adverbs, etc.) and parts of a sentence (subject, direct object, etc). You don't have to be a super-linguist or even achieve senior-editor proficiency, but know the terms for your craft.
I know a lot of this stuff, but spending an hour reading something like the Language Log or even the aforementioned Grammar Girl reminds me that there is plenty I don't know.[2]
10. Learn new tools and new ways to use your existing tools. It's hard to imagine a technical-writing career where the tools you use today are the same ones you'll be using in five years, even if you don't change jobs. Even if you're not looking for a job, it's an eye-opener to look at job listings for technical writing and see the kinds of tools that they would like to see you be familiar with.
This actually encompasses new techniques as well. Don't know XML? Always useful. If you regularly use text-editing tools, learning regular expressions will pay off (no matter how brain-breaking it seems). What do you know about graphics formats and how to create and edit them? Etc.
One of the writers I work with is a tool-a-holic who constantly plays with new tools and often regales us with tales about his latest discoveries. I kind of marvel at his appetite for constantly learning new tools, but the point is that he's always investigating and improving his tools skills.
11. Talk to other writers. Do you ever talk shop with other writers? As with anything else, you can learn a ton from others who do the same job. It can also be reassuring to learn that other people have the same problems — with writing, with editors, with SMEs — that you do, and in the spirit of "practicing," you might learn about things that might not come up in your day-to-day work.
12. Practice meta-skills. Writing is all well and good, but much of the job involves other skills as well. Are you uncomfortable talking to SMEs? Make it a point to do that for your next project. Volunteer to do a presentation for your team or (yikes) for a conference. Take on the task of managing a project — not just writing, but scheduling, tracking, etc.
As I say, there are many ways to flex your tech-writer muscles in order to make them better. The general point, tho, and as Yegge says, the important thing is not just to do the same thing over and over. You can already do that.
[categories]
writing
|
link
|