Archive for December, 2008

For eight years, I made most of my income from technical writing. Not the relatively glamorous technical writing involved with writing articles about free and open source software (FOSS) – glamorous, that is, to those who haven’t done it (those of us who have done it are usually considerably less starry-eyed) — but basic how-tos and detailed instructions to accompany hardware and software. Looking back, I must have been reasonably good at the job, since I went from a beginner to a consultant with a sub-contractor in eight months, and kept myself steadily employed most of the time and well-employed much of the time.

Based on that experience, I would like to offer some advice for those who are trying to fill the gaps in FOSS documentation. It’s a thankless job, under-appreciated and laborious, but, if you’re going to attempt it despite all the disincentives, you might as well do it properly. After all, your satisfaction in doing the job properly might easily be your only reward:

  • You must become an expert in what you are writing about: Some professional technical writers pride themselves on being specialists in communication, and feel they don’t need to know the details of what they are writing about. You can always tell manuals done by them, because they are shallow and have large gaps in them. Likewise, you can always tell this type of technical writer, because they’re despised by any developer with whom they work. The truth is that, while you don’t need to be an expert when you start documenting, if you aren’t expert by the time you’re finished, you aren’t doing the job properly.
  • It all comes down to structure: Anybody with average intelligence or better can learn to write a coherent sentence or paragraph. However, structuring several hundred pages is hard work – much harder work than the actual writing. The need to structure is also why you need to become an expert in your subject; if you’re not, how can you know what information to put first, or what’s missing? Don’t be surprised if you spend 50-75% of your time in planning the structure, or if your first outline changes drastically as you work. Both are indications that your work is developing the way that it should.
  • In the majority of cases, the best structure will be a list of tasks, arranged from the most basic or earliest to the most complex or latest: It will almost never be a list of menu items and taskbar icons, except in brief introductions to the interface. This task-orientation is a major reason why you need to be an expert in what you are writing – if you’re not, you won’t have any idea of what users might want to accomplish.
  • Think of your audience as being attention-deficit: Knowing your material is necessary, but it can also make you forget what new users need to hear. The best way to write to the level you need is to project yourself imaginatively into the position of a new user, but, if you can’t manage that, imagine that you are writing for people with low attention spans who are easily bored. The result may spell out the obvious for some readers, but other readers will be glad that you are thorough. Always remember: What is obvious to you isn’t obvious to your readers.
  • Don’t worry about style: In fiction, writers often call attention to their style. By contrast, non-fiction like technical writing is not about you. Your job is to provide simple, clear prose in which you are invisible. And if that sounds boring or unchallenging, you might consider Isaac Asimov’s observation that stain glass windows have been made for over a millennium, while clear glass was a much later development. In many ways, writing simply and clearly is much harder than writing with flourishes and personality. Focus on clarity and content, and let other style considerations take care of themselves. You’ll be surprised how well they work out without you thinking consciously about them.
  • Use structured prose whenever possible:Bullet lists, numbered lists, tables, and callouts on diagrams – all these techniques are conciser and easier to understand than straight prose
  • Your first draft is probably going to be terrible: But that doesn’t matter, so long as it improves by the end. What matters in the first draft is getting something that you or others can analyze for gaps and make estimates about the finished documentation from. Probably, the physical act of writing will be no more than 25% of your time. Often, it will be much less. If you’re planned properly, and begin writing with a thorough understanding, it should almost feel like an afterthought.
  • Don’t mix writing and editing: Writing is a creative process, editing a critical one. If you try to mix the two, you will probably do both poorly. You may also find yourself freezing up and being unable to write because your self-criticism is interfering with your ability to write.
  • Make sure editing is part of your schedule: Editing should not be a last-minuted effort. Instead, accept it as an important part of your schedule. Expect it to fill 10-20% of your time.
  • Editing is about structure as well as words: Editing is not just about spelling or correcting grammar. It’s just as much about the structure of the work.
  • Get second and third opinions: When you have just finished writing, you are probably unable to judge your work effectively. Get other people to review your work in as much detail as possible. If you can’t get other people to review, put the manuscript aside for several days. If you can’t put it aside, print it out, or take a break before returning to it.
  • Expect revisions: Based on my experience teaching first year composition at university, I can say that the average person takes 3 to 4 drafts to produce their best work. You may be naturally talented or reduce that number with practice, but don’t count on either until you have some experience.Make sure you budget the time. You’ll know if your efforts are succeeding if the general trend is that each draft becomes quicker and quicker to write. If that doesn’t happen – especially if you have to keep reinventing the structure or making major additions – then something is probably seriously wrong.

With any given piece of writing, you may not be able to follow each of these pieces of advice. Deadlines in particular may keep you from giving each of these points the attention it needs. But keep all these points in mind, and you will be more likely to write documentation that people actually use, instead of an after-thought to the software that is never used.

Read Full Post »

I was at the Simon Fraser University book store downtown this afternoon when the cashier recognized me as the instructor for a class she had taken over a decade ago. That sort of recognition happens less often than you might expect, although I must have taught five or six thousand students overall. But it does happen once or twice a year, and never fails to make me edgy with the start of panic.

Partly, my panic is due to the fact that so much has happened since my instructor days that I hardly feel like the same person I was then. My ambitions, my career, and my whole outlook have changed dramatically since then – and not just once, but two or three times. I’m not much for nostalgia, thinking it a form of self-indulgent depression, so I don’t particularly welcome the unexpected reminders of the past.

For another, my interactions with a former student is necessarily very different from the one we once had. I am informal to a fault, but, in the past, the student-instructor relationship put us in an unequal relation. Now when we meet, the relationship is more equal. Or it should be. But the former inequality still colors what happens unless we are very careful. And the last thing I want to be is condescending, or assuming a superiority I no longer had nor wanted in the first place.

Even more to the point, one or two meetings with former students haven’t always gone particularly well. One former student lives in my neighborhood, and we often exchange a sentence or two when we encounter each other running, but, with other students, the encounters haven’t been so smooth. One student looked me up asking for a recommendation for graduate school at a difficult time in my life, and was put out when I told her – truthfully – that under the then-current English Department chair, my recommendation wouldn’t do her very good. Another met me coming out of the Canada Games Swimming Pool in New Westminster, and only my sense of my own ridiculousness kept me from sucking my gut in while we talked.

But the main reason these meetings make me feel uneasy is that I wonder how I am remember. By my own estimation, I was a committed instructor with scintillating lectures and a good rapport with students – but, by that same measure, who isn’t? The fact that my evaluations and frequent rehiring suggest that my self-estimation is not complete fantasy doesn’t help any, because (for all I know, at times), I could be meeting one of the handful of students who disliked me or complained about a grade.

Told that I once taught someone, my first impulse is to blurt out something like, “Well, I hope you have happy memories of the class.” But that would sound like I am angling for the very approval that I want, making it impossible for me to know if the reply was sincere or given out of pity. At the very least, it would put the ex-student on the spot. So, instead, I make small talk, hoping that I will gradually pick up the impression of what the student thought of me.

And, usually it is positive, as I would know if I used any sense in the matter. After all, why would someone reveal themselves to me if they had any animosity? They’d either ignore me or bop me on the head with the nearest blunt instrument the moment my back was turned. But logic has little to do with my reaction, so I am always disconcerted by these meetings, and probably always will be.

Read Full Post »

Ron Telek, the Nisga’a carver, can always be counted on for the unexpected – anything from the disturbingly haunting to the eerily beautiful, and in every form imaginable. I’ve even seen a shaman marionette by him. Our latest acquisition, “Transformation Rattle: Eagle to Wolf” is no exception. Only a handful of other Northwest Coast artists could take a utilitarian object like a rattle and turn it into a sculpture while keeping it functional.whole-small

One of the characteristics I’m starting to associate with Telek’s pieces is an unusual degree of three-dimensional awareness in the design. Like many of his pieces, “Transformation Rattle” is impossible to capture fully with a single photo. I took five pictures for our records, and I’m not sure that I shouldn’t have taken a sixth to cover it fully.

The rattle consists of two parts: The rattle, which is the eagle, and the rattle’s base, a lean-looking wolf with a curved tail and, around its neck, a garland of cedar boughs. The rattle rests inside the tail, and can be removed from it. At first glance, you are lucky to notice that it’s a functional rattle. Your first clue is the leather wrapped around the bird’s tail as a hand grip, but even that could simply be part of the surreal sculpture.

The rattle depicts the transformation perhaps two-thirds of the way through. On the right side, the bird’s features are depicted fully, but the left side of the body is mostly blank, with the features indicated by a few indentations, and the wing by the grain of the wood.


Its feet, too, are gone, absorbed into the wolf. Perhaps to indicate the transformation’s incompleteness, the bird’s wing is wrapped around its rounded stomach, as though it is pregnant with itself.


The wolf is more complete, but its lack of claws and teeth or fully-formed rear legs shows that it, too, is an unfinished figure. wolf-small

Its thinness and slightly rough carving, especially in the comparison with the eagle further suggests the wolf’s incompleteness – and, perhaps, the energy expended to make the transformation.

The fact that the two figures are the same is suggested by the spirit in the middle of the eagle’s right wing and atop the wolf’s head. Furthermore, the wolf’s garland of cedar suggests that this is not a born wolf, but a human – no doubt a shaman – going through these transformations. Supporting this idea is the much larger, more human-looking spirit erupting from the wolf’s back, as well as the fact that, if you look closely, the rear legs are more human than wolf-like.wolf-front-small

All this complexity is heightened by Telek’s characteristic attention to the direction of the grain. An employee at the Art of Man Gallery in Victoria told me last week that Telek often carves down until he finds the grain he wants, and, looking at “Transformation Rattle,” I have no trouble believing it. Although both the rattle and its base is carved from a single piece of red cedar (and stop and think about the difficulty of that for a moment), the carving is literally never against the grain. Even on the wolf’s curving tail, the grain moves with the sculpture. And, on the eagle, the round pattern of the grain not only suggests the bird’s body, but creates a semi-abstract form as simple as it is beautiful.

The overall result is a contrast with the tall, rounded shape of the eagle, and the ground-hugging, angular shape of the wolf. It’s an accomplished piece of work, which I’ve place on top the shelves on my computer desk, where I can look up at it periodically, or even take the rattle out for a shake if I feel like it. We’re seriously thinking of mounting it on a lazy susan, so that it can be viewed in its entirety more easily. Meanwhile, I’ve already switched its position around several times in the day since we brought it home so I can admire another aspect of it.

Read Full Post »

Even if you’re an extrovert, meeting new people takes energy. To reduce the required energy, whenever I’m networking or at a business meeting, I like to come equipped with at least one conversational hook – a detail about me that make people curious and give them something to talk about when they approach me.

The term is borrowed from the writer’s idea of a hook, or first sentence that makes people want to read more. For example, when Charles Dickens started A Christmas Carol with, “Marley was dead to begin with,” he hoped that readers would be intrigued about why he would mention the fact. More subtly, when Jane Austen began Pride and Prejudice with “It is a truth universally acknowledged that a single man in possession of a good fortune must be in want of a wife,” she is announcing that her subject is courtship, hoping that it will interest them (and also, as you soon find out, being ironic, since the last thing that either Bingley or Darcy are thinking of at the start of the novel is getting married).

A conversational hook works the same way. Just as a literary hook lures you into reading, a conversational hook is designed to make others think that you are worth spending time with. It’s not as extreme as an eccentricity. Nor is it a pose, because, to be successful, a conversational hook needs to be backed up by the ability to talk about it. Rather, it is an expression of your individuality that attracts attention.

A conversational hook can be as simple as a T-shirt. When I am at a developers’ conference – and, sometimes, just on the street – My Linux Journal T-shirt, with the slogan, “In a world without fences, who needs gates?” (a reference, of course, to Bill Gates and Windows) is sure to evoke a laugh. And, once you have shared a laugh, talking with each other becomes easier.

More recently, I have found my three inch copper bracelet by Tsimshian artist Henry Green to be another conversational hook. Larger than usual, made of a metal that you rarely seen in jewelry, and featuring a stunning design, the bracelet offers all sorts of topics that people can use to approach me. First Nations people, especially artists, are especially interested in it, but the interest cuts across all sorts of demographics. One friendly acquaintance who has watched too much Doctor Who calls it my chronoplate, while others ask if I am wearing it because I believe that copper helps relieve arthritis. It helps that the bracelet is more suitable for formal occasions than a T-shirt, too.

You can use the same idea to make yourself stand out on a resume. Although I maintain several different resumes, I always include two or three lines under the heading of “Interests.” Currently, the section reads, “Running; parrots; punk folk music; Northwest Coast art; history, science fiction, and 19th century novels; Linux.” This summary not only says a lot about me and positions me – I hope – as a well-rounded individual who is worth interviewing.

In addition, when I am called into a job interview or consulting session, it gives other people a starting point. I have lost track of the number of times people have begun by asking me what punk folk music is, and many other meetings begin with an exchange of stories about running or science fiction. And I still remember the forty-five minute interview that consisted of five minutes of talk about the contract, and forty exchanging cute stories about our parrots.

Conversational hooks work because most people are nervous meeting new people. By giving them something to talk about, you set them at ease. In doing so, you generally create a favorable first impression – and first impressions, as you probably know, are frequently the basis for the impression that people take away from a meeting. Not only can you help yourself by creating hooks that draw other people in, but you can be on the lookout for hooks that others may be consciously or unconsciously offering.

Either way, you’ll find that conversational hooks are a great way to take the nervousness out of meeting people for everyone.

Read Full Post »

Not too many years ago, you only had to walk down Government Street in Victoria to find more shops selling Northwest Coast art than you could properly absorb in a day. Looking back, I’m not sure of the quality of some of the shops, but they were there. But times are harder, with many store fronts along Government empty, and now you have to search for galleries.

Descending on Victoria yesterday, these are the galleries we managed to find:

  • Art of Man: Located in the mall in the basis of the Empress Hotel, the Art of Man specializes in Inuit and First Nations masks and sculpture. The pieces for sale included four or five from Ron Telek, including a meter high blue shaman (this from an artist who rarely uses color), and a shaman marionette fending off a spirit attacking his foot with other spirits resting in his hand. Daryl Baker, the nephew of the LaFortune brothers Doug, Perry, and Aubrey, is also represented by highly-detailed designs that border on the surreal, and that are all marked by a close attention to finishing details. The Art of Man also seems to get first pick of Tim Paul’s work – so much so that I realize that only his lesser pieces reach Vancouver. Other artists whose work is available at this gallery are John and Luke Marston, whose work shows an awareness of history that I had never realized before that it possessed. In general, the quality of the work at the Art of Man is extremely high, making it by far the premier gallery of Northwest Coast art in downtown Victoria.
  • Hill’s Native Art: Like the Vancouver store, the Victoria Hills is mainly a tourist shop. However, the Victoria store seems to have a slightly better ratio of art to high-end tourist pieces, as though it gets first choice of all the locations. But perhaps this impression is due partly to the fact that it is less crowded and better lit.
  • Alcheringa Gallery: From the web site, I had the impression that this gallery was huge. The reality, though, is that this is a gallery with only a few of its pieces on display – and about half of those are given to works from Papua New Guinea, which is worth seeing, but doesn’t engage my interest the way that the Northwest Coast tradition does. Still, you can see some works by Tim Paul and John Marston there. I was also interested in seeing two works I had seen on the Internet, one by Ron Telek and another by Dean Heron.
  • Pacific Editions: Unfortunately, this story is closed on Mondays, which meant that we walked six blocks out of our way for nothing. But what we could see through the window confirmed the impression I had from the web site: Pacific Prints has a huge collection of limited editions prints. I look forward to spending a happy few hours there the next time I’m in Victoria.
  • Eagle Feather Gallery: A mixture of art and tourist pieces, this gallery is only a block from the Empress Hotel – but on a side street that you may have trouble finding. It specializes in the work of Doug, Perry, and Aubrey LaFortune, especially Doug (in fact, he was due to drop by the day that we visited, although we missed him). Daryl Baker and Pat Amos also have a couple of pieces, while Francis Dick has at least a dozen 2-D works from throughout his career at the gallery. Whether the gallery is worth a visit probably depends on your opinions of these artists, although its stock gives you a good opportunity of evaluating Doug LaFortune thoroughly.
  • Out of the Mist Gallery: This gallery specializes in antiques. Its modern selection is devoted largely to the Hunt family, and includes a few curios like a mask carved by Richard Hunt when he was a teenager, a formal, somewhat stiff print from the start of Beau Dick’s career, and a two meter-long eagle by Roy Henry Vickers. The quality of the antiques is completely indiscriminate, and includes some pieces from across North America. If your taste runs to antiques in Northwest Coast art, you could probably find something to your taste, but the somewhat dim lightning and the bored staff makes the effort hardly seem worthwhile.

As with previous lists I’ve made of galleries, this one makes no effort to be comprehensive. We did not, for instance, have to visit the Provincial Museum’s gift shop, which I seem to remember as having a few art pieces. So if you know of any other galleries in the Victoria area that might be worth a visit, please add a comment and let me know.

Read Full Post »

« Newer Posts