bravo to Chrysler's

head of technical publications:

Chrysler announced that digital owners’ manuals will replace their paper predecessors starting in 2010. The automaker is the first to switch from dead trees to DVDs, and estimates the move will save 930 tons of paper annually.

read on: http://www.wired.com/autopia/2009/09/chrysler-eliminates-the-paper-owners-manual/

documentation nightmares: car seats

I was going to make this post 3 years ago, but didn't. Now I have another opportunity.

I consider myself technically adept at mechanical things. 

• Building Ikea furniture? Easy and fast - rarely do I need the directions.
  
• Fix my car? Sure, I'm at home under the hood and under the chassis.
  
• Soldering circuits? Been doing that since 6th grade.
  
• Fear of disassembling anything? Nope not really.
  

So you would think that installing a car seat would pose no problem, especially after I've had experience, and considering I am a documentation professional. Well, no.

Certainly you want absolutely 0 margin of error for your car seat installation. This is my family's 3rd car seat - the one we purchased this weekend was a Booster / forward-facing-harness seat. And like I always do, I stuck to the directions. And that's where I failed.

Here's the problem as I see it: The pocket-sized, 35-page guide includes procedures for:

• Booster seat operation
  
• Harness seat operation
  

And attaching the seat to the vehicle via:

• LATCH
  
• Seatbelt with shoulder strap
  
• Seatbelt without shoulder strap
  

So that's potentially 6 scenarios. In addition, the text warns of procedures not to follow that may only be applicable to the scenario you are not following. It's confusing, not reassuring, and highly annoying. 

My guess is they cram all this information into a little booklet to stay attached to the car seat, and the lack of clear directions is probably designed so they can CYA, legally.

I don't object to including the product manual as is, but they should publish more refined instructions in a larger format. A nice 2' x 3' poster with line graphics that tells you each step you must explicitly follow would be a great start. In fact, one poster-sized document per scenario would be very good.  Personally I think the best solution would be for their documentation to interface with a database of car specifications. You could go to the website, choose the car seat model, choose your car model, and their system would automatically generate the documentation you need.

(Image courtesy of  dfb)

my failure as a blogger

I've been around the block on the Internet. I got my first Internet email account the 2nd or 3rd week of college in '91. To me, the WWW is just one part of the Internet. But obviously things change and mature and I haven't kept up. Which is to say I used to be thoroughly engaged in the culture and society of the Internet, but as we're in post-Web2.0 times, I have lonely facebook, myspace and livejournal pages. My 4 or 5 blogger accounts are mostly stagnant, and my personal website is used as a photo album to share with my family who lives out of state.

I love the technology, but for several years the web has been about people and interpersonal communication more than anything, and I haven't really kept up in this realm. 

So the other night Arianna Huffington was on john stewart, pushing her book on blogging. Within 6 minutes time she shed light on why it's so tough for me to gain any traction blogging. 

First she says "blog your passions." Ok that's not too tough. I love to write about I have thoughts and opinions I'd like to share about tech writing, and tech, and media, and music (and their intersections). But then she said how blogging is about getting your thoughts down and firing them off quickly...

Do you know how many draft blog posts I have saved???? I think the TW in me wants to take the time to write down concise thoughts, not leave ideas hanging, and try to direct the reader toward a conclusion (don't you just hate it when you post about X, and the thread goes to some minor point you made in passing that could have just as well been left alone???)

My wife turned to me and said "you even write out your phone calls before you make them!!" (which i do sometimes because I want a precise query).

Perhaps this is where my shortcomings of being a real writer is apparent: Given a controlled topic to write on, I'm good and fast. But given the task of writing open-ended, engaging prose that people want to read and respond to, I fall short.

The Daily Show With Jon StewartM - Th 11p / 10c

Arianna Huffington

Barack Obama Interview
John McCain Interview

Sarah Palin Video
Funny Election Video

why the attention?

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

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. 

steel cage job title championship match

Two disclaimers:

1. I acknowledge that these titles are arbitrary.
2. The distinction I describe is my own and my thoughts probably represent the minority.

Less so in recent years because I've had steady, happy employment, but I often agonize over the definitions of technical writer vis-à-vis applying to job postings. Documentation Specialist is probably the second most common job title (which I held in two government positions) which every TW-type job applicant searches. So when one is bored, fretting, and unemployed, trying to sort out the difference between the two is happily time-consuming. I'll add that the HR people who submit job postings probably don't give the difference a second though. But you know, we're writers - so we obsess over definitions.

I don't know if this was the purpose of the blog entry or not, but Collin Turner's discussion of a subject matter expert (SME) has helped me make a sharp distinction between technical writer and documentation specialist.

SME is a term that's thrown around loosely (at least in my experience), but Turner starts with a salient point in that an SME "provides needed content." The SME is the source of the content. The documentation specialist then chaperones the content through the documentation process until a product is published.

In my limited world view, I'll suggest the following difference: While neither the technical writer nor documentation specialist creates the product (computer application, piece of hardware, or process) that must be documented, the technical writer creates and is ultimate responsibility for the content supporting the product. He or she performs the requisite research inside and outside of an organization to identify, collect, and organize this content.

Collin Turner's description acknowledges these internal conflicts, but lays the organizational knowledge arbitration at the SME's feet.

When I am wearing my technical writer hat (which I like to wear most of the time), I am navigating my organization and available resources to identify and collect all the required content. This means obtaining different functional organizations' ideas of a product, resolving their differences, and presenting a unified view.** Secondarily, I need to have confidence that I can identify with the target audience in order to create effective documentation from the raw data which I've gleaned. This is a real world description, not some idealistic cut and paste from engineering and marketing documents, fix the grammar and save as perfect documentation dream.

I generally feel that a good technical writer must become competent enough in the subject he or she is writing about to answer most questions about it. In the SME-documentation specialist system, the DS has a place to ask questions, but isn't ultimately responsible for the content.

The biggest problem that I see is when an SME doesn't have a vested interest in the user and doesn't take the time to understand the user's documentation and learning needs. When the SME is an engineer or scientist, he or she is too busy creating the widget. But this system succeeds when the SME is in marketing and understands that his or her success or failure depends on the customer's success or failure.

**Any good TW knows that his or her understanding of cross-departmental viewpoints somehow is really valuable to the organization. If anyone in upper management realized this too, I think that TW's organizational roles could be elevated.