I recently posted a short tip on the Visual Studio Magazine website where I mentioned that I often comment out code because I never know when I might "want it back". This lead to a whole bunch of comments that I was foolish not to use source control. I suspect that it was the word "back" that caused readers to think that I was using comments as a substitute for keeping track of the changes to my code. In reality, I was doing something different (though, perhaps, equally reprehensible: using the version tracking system as a repository for code that, while not useful now, I might want later). What was interesting were the people who went from the initial assumption that I didn't use a key software tool to assumptions about what other nefarious practices I might engage in.
It occurs to me that this reflects the major problem that technical writers (or course designers) make: assumptions about the audience--the most common assumption being that the audience is just like the author. I recently recognized that I had fallen prey to this myself.
I was in New York last week teaching, for the first time, a Learning Tree course that I had rewritten last spring. I had included some technology in that course without any explanation to the audience: I simply assumed that, by the time the course ran, most people in the audience would be familiar with it. That turned out not to be the case. What's especially irritating about this is that I've been polling participants in other classes and knew that the technology wasn't well adopted yet.
So now I have two choices: Take the time to get participants up to speed in the technology or remove it from the course. Right now, I'm leaning towards removing it from the course. The technology isn't really core to the course's mandate and, quite frankly, the course is tight for time. However, there's a conference call coming up with the instructors for the course on Monday. The instructor pool for this course is excellent and they may well have a different perspective on the problem than I do.
By the way, while some of the commenters on that original tip only wanted to abuse me for my perceived short comings, several demonstrated what makes a great technical writer: they wanted to take the time to either correct my behaviour or, at the very least, to warn off other readers about the perils of doing what they thought I was doing.
Reading or read:
It occurs to me that this reflects the major problem that technical writers (or course designers) make: assumptions about the audience--the most common assumption being that the audience is just like the author. I recently recognized that I had fallen prey to this myself.
I was in New York last week teaching, for the first time, a Learning Tree course that I had rewritten last spring. I had included some technology in that course without any explanation to the audience: I simply assumed that, by the time the course ran, most people in the audience would be familiar with it. That turned out not to be the case. What's especially irritating about this is that I've been polling participants in other classes and knew that the technology wasn't well adopted yet.
So now I have two choices: Take the time to get participants up to speed in the technology or remove it from the course. Right now, I'm leaning towards removing it from the course. The technology isn't really core to the course's mandate and, quite frankly, the course is tight for time. However, there's a conference call coming up with the instructors for the course on Monday. The instructor pool for this course is excellent and they may well have a different perspective on the problem than I do.
By the way, while some of the commenters on that original tip only wanted to abuse me for my perceived short comings, several demonstrated what makes a great technical writer: they wanted to take the time to either correct my behaviour or, at the very least, to warn off other readers about the perils of doing what they thought I was doing.
Reading or read:
- A Sentimental Journey and Other Writings by Laurence Sterne
- The Hamlet by William Faulkner
- The Day of the Locust by Nathanael West
- Moon Over Manifest by Clare Vanderpool
- Word After Word After Word by Patrica MacLachlan
- Castle Rackrent by Maria Edgeworth
- Portnoy's Complaint by Philip Roth
- Airships by Barry Hannah
- Three Novels: Soft Soap/The Leg/Will-o'-the-Wisp. by Willem. Elsschot
- Chapel Road by Louis Paul Boon
- Gustave Courbet by Sylvain Amic, Kathryn Calley Galitz, Laurence des Cars and Gustave Courbet
Posts
No comments:
Post a Comment