Playing by Ear
Recently, a couple of my co-workers have become obsessed with the video game Rock Band. After getting the gist of Rock Band’s premise, I began to think about why I might find it frustrating. It sounds essentially like an exercise in sight reading, that is, the ability to read notes (or in this case colors) and play the correct note for the correct duration at the correct time.
The musician who sight reads may not have quite the same intuitive feel for the music and may lose some of the emotional nuance of the piece (although this certainly isn’t always true). On the other hand, someone who plays by ear may miss some of the detail of the piece, but nail the feel of it perfectly. (Again, not always true.)
While listening to my co-workers sing the praises of Rock Band, I’ve been writing some documentation aimed at software developers. It’s got me thinking about whether some programmers essentially “play by ear” too. Because it’s not done in real time, programming is not quite like musical performance. Yet, I think that a programmer who only occasionally glances at a language reference is more akin to a musician who plays by ear. On the other hand, someone who relies heavily on sample code, developer guides, and even code creation wizards is more like a musician who sight reads. Is one style of programming better than another? I don’t think so.
Yet, there are implications, for presenting the right information, to the right audience, in the best format, at the right time. Metaphorically speaking, some programmers want the entire score, note by note. Others only need the occasional reminder of syntax. Putting the wrong material in the hands of either developer is a guaranteed recipe for frustration.
None of this is new, of course. What is new to me, however, is the freedom to design the documentation without any of the corporate constraints and guidelines that have been both a help and a hindrance in my former tech writing positions. In short, I’ve got to opportunity to invent a slightly better doc wheel. And all you software developers have an opportunity too. To tell me what makes great documentation, whether you program “by ear” or by “sight reading.”
Feel free to send me feedback. I’m all ears. (Sorry, couldn’t resist.)
December 12th, 2007 at 6:47 pm
Hi Anne - it’s one of your online friends from NZ!
I’m not quite sure how I found myself here, but here I am anyway… ;o)
Interesting thoughts above. Personally I am more in the “playing by ear” category of developers, but it definitely varies depending on the requirements. It did remind me of a job interview I had a couple of years ago, where I was asked to sit a ColdFusion “test”. This consisted of 50 multiple choice questions, most of which required me to know (off the top of my head) what variables and attributes were required for various tags. This is not generally something I memorise, rather I rely on the context-sensitive help for the tag. I scored around 65% (I surprised myself a little!) but the “pass” mark was 80%, and I wasn’t considered for the job. But I do wonder how many developers would have achieved the required pass mark, given the “advances” in technical writing, etc.
So is our reliance on built-in help references a good thing, or a bad thing? I guess it comes down to the individual, but personally speaking, I’d rather not have to memorise hundreds of tag definitions. I’d rather concentrate on remembering good coding practices and spending more time on analysis and making sure the client gets what they need and want.
December 13th, 2007 at 10:02 am
Oddly enough, when I interviewed for this job, one of my interviewers asked me language specific questions, like what’s the SQL to extract particular sets of records from a database. I literally had to put my hands in the position of typing, as though I had a keyboard in front of me. I guess I did well enough to get the job.
As a tech writer, I’ve worked in lots of different languages, but not daily. I flit from one to the other, probably knowing just enough to be dangerous, but not enough to be truly expert in any one language. I suspect that’s true of many tech writers. I’m one of thos people who has quick references littering my bookshelf. I would have loved to have a handful of them in the aforementioned interview. But I suppose that might be something like bringing crib notes into an exam.
Anyway, thanks for the feedback!