Dejargonize your documentation

by

I recently attended a product demo given by an Apple representative. It was held in the local music store and covered the latest versions of Garage Band and Logic Pro.

During the demonstration the rep showed how Garage Band can adjust the timing of recorded audio tracks, such as a live drum take recorded using a microphone. Adjusting the timing of instrument tracks recorded using MIDI (Musical Instrument Digital Interface) is old hat. It’s known as “quantization”. However, the ability to adjust the timing of an audio track is a novel development. He stressed that it could only be done to audio tracks that are recorded with Garageband, and not to audio tracks that are recorded elsewhere and imported into Garageband.

I asked him: “Does Garageband store some kind of metadata for audio files that it records?” He replied: “No, it stores additional information along with the sound file.” Then he paused, and said: “…which is pretty much the definition of metadata“.

It was interesting to me to see the contrast in communication style. Garageband is designed, as he explained: “for people who know nothing about making music“. As such it avoids using the jargon regularly employed by those familiar with music-making technology. Quantization becomes adjust timing. Metadata becomes additional information.

Sometimes a concept benefits from a precise technical term, sometimes it just serves to make the material harder to understand for someone unfamiliar with it.

As someone who knows what quantization and metadata are, I had no problem understanding what he was talking about when he talked about adjusting timing and storing additional information. The reverse is not true: someone who can grok* adjusting timing and storing additional information may be left completely in the dark when the terms quantization and metadata are used. It’s not that the subject matter has changed and is any harder to understand, but the use of unfamiliar terms reduces comprehensibility by raising the bar for the audience.

Glossaries can help, and so can really thinking about the choice of words: “Can I say this in a more direct, simple way, without using “jargon”?”

Something to keep in mind.

* to grok = to understand

Advertisements

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: