Tuesday, November 04, 2008

why the attention?

| 1 comments |

So why am I ranting about subject-oriented technical writing? Well for reasons of fate, it's the primary type of writing I've done in my professional life. I'm proud of my work, and I'm proud of what good S-O TWing can accomplish. Yet, I feel like it gets shafted in technical writing communities. (hey, my baby is beautiful too!)


Take a glance at the excellent Writer River. If you read past the headlines, you'll notice that many of the submissions focus on user-oriented writing. I used to read techwr-l regularly, and besides their discussions on the inanities of grammar, and implementing single sourcing through structured languages, the most talked about topic was creating effective documentation through user-centric writing and what it means to be user-centric. 

Another reason why S-O TWing gets the shaft is the more the writing is only responsible to the facts, the more it's feared by the average professional writer. I say this not from first hand experience, but I'm drawing from years of reading technical writers' ramblings. The essence is that most TWers like to engage in the act of writing (which might have been what brought them to TWing in the first place). Yet S-O TWing zaps much of the enjoyable art and craft from the exercise.

There's also no ongoing writing challenge in S-O writing after you get it: once you master the logic of presenting clear, factual, expository or descriptive writing, you've got the craft. What can only sustain you this point is enthusiasm for the content itself.

Like everything, this is not black or white. While I can say that my work is mostly S-O writing, if I said that there are no user considerations, I'd be lying. In real life, my work severely tilts heavily toward being responsible to the content, but I'm still mindful that the reader is trying to get a job done. I'm still going to use transition words to make the reading flow, I'm still going to use visual formatting cues to make the document easy for the eyes to follow, and I still mix up sentence patterns so that I don't present 1000 pages of S-V-O constructions.

One final note: While S-O writing product usually falls into the class of a project's requirement, it's a business formality. It communicates concepts and details for the sake of reliability and sustainability. Using S-O writing for user-centric purposes gets all sticky, but that's the subject of another post.

subject oriented technical writing

| 0 comments |

It's been bugging to write down some of my thoughts on a fundamental technical writing dichotomy. Before we can even talk about audience, realize that your documents fall into the following camps (or a combination thereof):

  • user-oriented
  • subject-oriented
This is important to consider and be cognizant of because subject oriented TWing gets comparatively little attention, yet I believe encompasses a huge amount of professional technical writing output. So I'll give my quick, ideologically-pure definition of subject-oriented writing.
Subject oriented technical writing is only responsive to the topic it documents. It must faithfully and completely explain itself and create new context and explanation where needed. It is legalese in form and does not owe anything to its creator or reader.
So, any time you are hired to document an organization's system, process, or configuration, you are primarily hired to create this type of content. Usually, subject oriented technical writing is a contract requirement meant to capture how the contract was executed. And what's the final destination of this product? Well it ends up on the shelf in a binder, in an archive directory, or on a CD or backup tape stored in a mountainside. No glory for the writer.

Let it be said that subject oriented technical writing is dry by nature; it is not sexy; it is just the facts & perhaps even-handedly considered opinions. As a computer industry writer, let me say that the shining example of this type of writing is the collection of RFCs
 
I would guess that something like a tenth of all technical writing is purely subject oriented.