Going beyond a shared understanding…sort of

As a writer working in the software field, I often hear a lot of ideas that aren’t expressed very well. Well, they’re expressed in specifications or in code. They’re just not expressed in actual communication that someone who doesn’t read specifications or code would understand.

And that’s where the technical writer comes in.

Technical writers are like the Bee Gees: words are all we have [1].  If something isn’t detailed, we can’t pass it along as it is to our readers, hoping they will understand. We can either help shape what is there into something comprehensible or we can make it up (but this second option puts the content outside the technical communications genre, and into creative fiction).

For the most part, engineers are like normal people (I said “for the most part”). Normal people and engineers have shared understandings. Most of us are part of communities that share nuances and unspoken ideas. I’m always surprised at how often communication is achieved without words. Often our best communication is not written down. We can get away without words because we share some underlying understandings with our community group.

But shared understandings aren’t complete laws for communicating to others. Rather, these understandings are shortcuts. For example, you describe something I have never heard about before. I ask you if it’s like something that I know about and that I presume you know about. If you hold your hand out flat, palm down, and twist it from side to side, I know you mean, “sort of.”

Most people don’t have to extrapolate from shared “sort of” understandings. In fact, as long as we keep to our own shared understanding group, we never have to explain.

However, a writer is a person who translates shared understandings into words that outsiders can understand. Writers are essentially translators of some world (fictional) or some community (technical) to their readers.

And that’s what I try do.

[1] For the youngsters:

Advertisements

About scotmarvin

Scot is a writer for Oracle. He's a slacker and smartass involved in content strategy, content architecture, big data, cloud computing, and other buzzwords related to technical stuff. He loves his family, history books, jazz guitar, and the Minnesota Vikings. Scot is a proud father, so don't make the mistake of asking about his family unless you have four hours to listen to him ramble on about his kids.
This entry was posted in documentation. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

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