Search This Blog

Tuesday, March 19, 2019

Technical Writing: No Room for Egos

When you are a technical writer or you want to be one, the first rule is this: It's not about you! But if you balk at this, you'll be sorely disappointed. And honestly, technical writing isn't for you.

Not All Writers Are Equal

Technical writing is a writing role where you are there to serve others. You are not writing something that emanates from your muse or your inner author. If you want to do this, then move on to creative writing. No slight at authors. I have great respect for some authors. I enjoy their works and learn from them. They can craft masterpieces, which is something I don't think I can do. My hat goes off to them. But these authors, as far as I know, are not technical writers. They do their thing. I do mine. We are just different. There's no comparison. As writers, we just have our own place in this world.

Writing For Others

As a technical writer, you are documenting something for another person.  It's about using your writing abilities to help them. You put your desires and agendas aside for your audience.

One of the first steps to writing a document is understanding who is your audience. Knowing your audience is the foundation in technical writing. If you don't serve your audience well or don't care at all, then the document will reflect that. Technical writing wouldn't exist if we had no audience to serve.

As a technical writer, you get no credit from the audience or even from the organization you are writing for. Almost always, there's no byline. You are basically a ghostwriter for the organization who wants to reach out to their audience. You do the work and they get the credit. That's how it is. Is it unfair? Yes. But remember: It's not about you!

I'll get into this more later on.

This Reluctant Calling Changed My Thinking

But first, I have a confession: I hated the idea of being a technical writer. Many years ago, I tried my hand as a journalist. I was told numerous times by editors journalism wasn't for me. They said I would be better suited as a technical writer because I wrote in a dry and matter-of-fact prose.  When I heard this, I was insulted. But this "insult" made me take a look into the mirror as to why I was writing in the first place. Unfortunately, I was writing for the wrong motives. I wanted my name out there and wanted to glorify myself. But God had other plans. After my fruitless pursuit in journalism, I reluctantly went into technical writing and the rest is history.

It used to bother me that I didn't see my name on a user manual or a brochure. It wasn't until I realized technical writing wasn't about me. It's about others. When I realized I wanted to help others through my writing, I was able to fully embrace this, quite frankly, weird form of writing.

Wear This Freakish Badge with Honor

Authors, such as Kurt Vonnegut, had keen insight about technical writers. Vonnegut aptly describes this strange form of writing:

"... technical writers are trained to reveal almost nothing about themselves in their writing. This makes them freaks in the world of writers, since almost all of the other ink-stained wretches in that world reveal a lot about themselves to the reader."

Though you don't reveal anything about yourself when you write, you use your writing to impact countless lives. You help those you may never meet by showing them or how to do something or informing about them some vital (maybe life saving) information. You may never know who you helped but you've helped them nonetheless. So wear this freakish badge with honor. And, stay humble as you write along.

Abandon Greatness and Seek a Servant's Heart

This may be contrarian when I say this: But to be a good technical writer, you must abandon any hopes of greatness. Rather, seek a servant's heart. Greatness and technical writing don't go together. When I mean by greatness, I don't mean great work. You should definitely strive to write a document well. What I mean by greatness is the potential prestige and fame like of a best-selling author or some well-known journalist. Sorry, it just doesn't happen with technical writing.

Technical writing is neither prestigious nor great. It's hard work where you get no substantial recognition for it. Others, like the big-wigs, get the credit or the fame while we remain in the shadows, faceless with our heads down typing away. And that's okay, let them bask in the glory. (Besides, if something goes wrong, they will get the brunt of the dissatisfaction.)

We are simply here to serve others. But don't forget: If you do this well, your writing has lasting, helpful effects on others more than the fleeting praises of fame and momentary pats on the back.

So which is better? Knowing you made a difference somewhere to help someone (maybe even saved someone's life) or hoping to get recognition and fame from others.

Knowing human nature, why would anyone want to fall prey to the Sirens called Fame, Recognition, and Prestige. One moment, the people sing you praise, heartily pat you on the back, and place you on a pedestal. The next moment, when you're enchanted with their song, they wedge a sharp, ugly blade deep into your back, twist it, and break it off at the hilt, and howl for your downfall. Then, proceed to slap you off your pedestal, where you fall to the ground and shatter into pieces. Then for the big finish, they jump on the shattered bits till you're nothing but powder.

I'd rather seek a servant's heart. For myself, I know God sees this and others get help they need, even though I rarely get a thank you for it. It gives me satisfaction I helped somebody, even if they don't know who I am. And if they saw me, they may say who's this schlub but that's okay. It's not about me. So, let me leave you with a snippet from the Gospel of Luke about how this world has it upside down.

A dispute also arose among them as to which one of them was to be regarded as the greatest.  But he [Jesus] said to them, “The kings of the Gentiles lord it over them; and those in authority over them are called benefactors. But not so with you; rather the greatest among you must become like the youngest, and the leader like one who serves.  For who is greater, the one who is at the table or the one who serves? Is it not the one at the table? But I am among you as one who serves."  — Luke 22:24-27 NRSV

Friday, March 1, 2019

Count All the Steps

When you read a set of instructions or a user guide and it doesn't make sense, you might be thinking someone is just writing a step-by-step so how they can screw this up. can.

When you create a set of instructions or a manual, you can easily overlook how many steps it takes to perform an action. This is especially true if you do something constantly. Whenever you're doing something all the time, you don't really think about the actual steps that go into it. I'm amazed how many things I miss before I get it right whenever I'm documenting something, including things I do all the time.

Whenever you have to write instructions, remember this: There's a lot more steps than you think. But this deceptively easy task isn't hopeless. You can document all the steps if you remember to count all the steps.

Here are some tips I found helpful when doing some good ole technical writing.

Write How You Naturally Do Something

If you're documenting how to do something, especially if it's something you do over and over, then just relax and simply write out the steps involved. This gives you a good starting point when you're writing a set of instructions or a manual. The keyword phrase to remember is "a good starting point."

Stop and Think

Once you've written out the steps, it's easy to move on. Don't! Stop and think. Ask yourself did I document all the steps needed. Forcing a mental pause will determine the difference between a great set of instructions where you actually help people to do something and ones people get frustrated with and toss to the side to try to figure it out for themselves.  They're coming to us for help when they read a manual. We have let sloppy instructions go out for far too long. This needs to stop.

Check Your Steps  

Once you made a mental pause, it's time to check your steps. To do this, simply go back to the first step and take it from there until you get to the last step. I have found when I go through each step, I end up adding a few more steps or revising ones what I wrote. And, there are even times when I have taken out some unnecessary steps. 

Keep going through the steps until you have documented everything. But how will you know when it's done? Well, if you wrote out every step and went through them, you will accomplish what you were intending to do. You should be able to assemble that product, installed that software, or performed that certain action. The point of steps to get the reader to the desired destination.

Pretend You're the Reader

Once you checked your steps, it's time to become the reader. Well...didn't you do that when check you the steps? Yes and No. You may have looked at the individual steps but not the whole picture of the document.

When you become the reader, take it from the top and ask yourself two questions. One, is this right information for me? Two, are these instructions helpful?

Am I (as the reader) a technical professional or a layperson? This helps knowing what kind of steps or information should be in the document.

Even though you should ask yourself who are my readers before you put pen to notepad or keystroke to keyboard to create a document, you need to ask yourself this question again as you're reading to make sure you didn't miss the point of the document. This should be the first question you should ask yourself.

Once you do that, you can ask yourself if these instructions are actually helpful. Are the steps easy to follow? Are they accurate? Does the document easily flow from one topic to another? Are the graphics in the instructions easy to see or they fuzzy or overwhelming? Is the font easy on the eyes? These things play into the fact to ask yourself if these instructions are helpful.

Also, if you can, try reading out the steps and text out loud. When you do this, you'll be surprised at what you catch. If it sounds awkward, you can make whatever changes you need.

If the steps you wrote don't address the right kind of readers or are not helpful, then this document is nowhere close to going out. Make sure you fix this before you publish them. 

The world doesn't need another set of unhelpful set of instructions or a hard-to-understand user guide.

Brewing Coffee

Okay, I have done enough talking about this. Now, let me show you a set of instructions on how to do something seemingly simple but actually involves quite bit of steps—Brewing coffee. I didn't realize how many steps were involved until I wrote them. Please check the document below.