Happy holidays & a recommended read

Kai’s Tech Writing Blog takes a break for the rest of the year. I wish you a happy holiday season, and I’ll see you in early 2011.

Cover of Paul Harding's book TinkersIf you’re looking for a change of pace, I can recommend a great, but short book: Paul Harding’s Pulitzer Prize-winning novel Tinkers makes for slow wonderful reading as the main character thinks back on his and his father’s life in rural New England through the 20th century.

Interspersed with the narrative are excerpts from the Rev. Kenner Davenport’s The Reasonable Horologist from 1783. This instructional text is a great example for artful and stylish documentation:

Now, the horologist looks upon an openfaced, fairy-book contraption; gears lean to and fro like a lazy machine in a dream. The universe’s time cannot be marked thusly. Such a crooked and flimsy device could only keep the fantastic hours of unruly ghosts. The front plate of the works is taken in hand and fitted first onto the upfacing arbors of the main and strike springs, these being the largest and most easily fitted of the sundry parts. This accomplished, the horologist then lifts the rickety sandwich of loose guts to eye level, holding the works approximately together by squeezing the two plates, taking care to apply neither too much pressure (thus damaging the finer of the unaligned arbor ends) nor too little (thus causing the half-re-formed machine to disassemble itself back into its various constituent parts, which often flee to dusty and obscure nooks throughout the horologist’s workshop, causing much profaning and blasphemy).


The power of trust and enthusiasm

The bright side of networking is that you can get help from great people – if you let them… That sums up my experiences at the office, at conferences and at this blog.

As I look back at the last two years, I’m really grateful to have a bunch of great colleagues, fellow tech writers, and friends. Some of them I met almost every working day, some I meet at conferences, others I only know from blog comments and tweets. But all of them inspire me when I feel empty, they give me advice when I’m stuck, they keep me on my toes when I’m tempted to slack off, and they give me confidence that what I’m doing is worthwhile. The mystery is that I can never quite tell where inspiration or help may be coming from.

Here are some anecdotes from the last couple of years where I’ve had help in unexpected ways.

How I went to tech writing conference

One of the blogs I’ve been reading for a long time is Scott and Aaron‘s DMN Communications. On January 20 last year, they gave away a couple of tickets to the now defunct DocTrain West conference, though you had to pay our own way.

I figured that a free pass would be a enough of a compelling event for me to make it to the conference somehow, so I put in my name. I won a pass, my employer was compelled, and we shared the rest of the cost. I had a blast at DocTrain West. And I thank Scott and Aaron for the opportunity.

How I started a blog

In January of this year, I had one of those Friday afternoons: It was past the deadline, and I was still trying to align the documentation with what would be shipped. Something about a dysfunctional process set me off. It was one of those frustrating moments when it’s painfully obvious that you won’t get good documentation if you don’t keep writers in the loop.

I must’ve looked pretty frazzled when I complained to a colleague at length. She just looked at me and said: “I don’t think you should rely on your colleagues’ cooperation to be happy with your work.” She was right. Over the weekend, I set up this blog where I can share what excites me about technical writing. Much of it turns out to focus on my experiences as a lone writer. And I thank Daniela for her great advice.

How I submitted a proposal for a talk

This year, TCUK and WritersUA were within a week of each other. I only had time to attend one of them, so I asked about differences and recommendations on twitter. Some replies were encouraging, along the lines of: “They’re both good!” 🙂

Then Linda Urban, who I had met at DocTrain West, pointed out that TCUK waives the conference fee for speakers, if that made any difference. And that the deadline for proposals was the next day.

I had already thought of submitting a talk to tekom, but hadn’t, mainly because I thought it wouldn’t be suitable. So I wrote up my proposal about “Getting ahead as a lone writer” and sent it in. It was accepted, and I thank Linda for her encouragement.

How I got over stage fright

So there I am at TCUK on the evening before my talk. Yes, I believe I’m reasonably well prepared, but I can’t help getting nervous. So over dinner, I start to talk to Karen Mardahl.

She asks me what my talk will be about and what I’ve done to prepare. She assures me that my agenda sounds relevant and that I shouldn’t worry too much. After the talk, I knew she’d been right. And I thank Karen for her support when I needed it.

– Trust and enthusiasm, mine and that of other people, have often seen me through, when I ran out of other options – as all of these events remind me.

Your turn

Can you remember similar moments in your career, when you were in need of help and received it where you couldn’t necessarily expect it? Or when you could give such support to someone who needed it?

Feel free to leave a comment – but it’s probably more important to remember and to cherish such moments.

How efficient is your documentation?

To gauge the efficiency of your documentation, consider the time spent to create it plus the time it takes to use it.

That’s the lesson I learned from applying Scott Berkun’s make vs. consume ratio to documentation. Scott’s idea is generally that it takes time A to create a tweet or a poem, a book or a movie, and time B to read or watch it. Scott relates the two measures and points out how you can easily consume in a few hours what authors and publishers, actors and movie people have spent months fabricating.

“make + consume” in documentation

When it comes to documentation, I think you can add both measures to gauge efficiency of documentation – though not its coverage or quality!

But just for time, I try to keep in mind these tactics:

  • Minimize the total time required for you to create your documentation and for customers to find, use and apply it.
  • Consider spending more time to make your documentation faster and easier to use, especially if you find that customers have trouble with it.
  • Consider spending less time with documentation tasks that do not help your customers in using the described product.

Of course, time isn’t the only yardstick. Accuracy, completeness, legal and contractual obligations are just some of the other factors.

Still, I’ve found “make+consume time” a useful benchmark to stay focused on what ultimately benefits the user and what doesn’t.

Further reading

If you’re concerned about documentation efficiency, you might also find earlier posts of interest:

Your turn

How do you gauge the efficiency of your documentation process and output? Can you credit your efforts towards making your documentation faster and easier to use? Please leave a comment.