Technical Writing Rule #13

another in a series of rules that all technical writes must know

Engineers are wrong, a lot of the time. Don't assume that what they tell you is truth UNLESS they are the primary person responsible for the discrete piece of code or equipment you are inquiring on.

A really good technical writer will know the system to be documented holistically, and should be able to notice all inconsistencies.

action or subject

Pretend you are a user for a second, and not the technical writer. When you read a manual, do you, personally, want an action/task or subject oriented arrangement?

Over and over it is drilled into our little TW heads that everything should be action-oriented because the users are reading your prose to get something done for their job.

Maybe this is an overy-geeky opinion, maybe it's just me, but I don't think this is a fair assumption. I'm reading about a technology that I'm interested in and have background in. I don't really want someone to tell me how to do my job, I want someone to tell me the theory, all pitfalls noted and let me piece together my own procedure.

I can't be all alone here.

value vs reality!

via C-Net's article about Nicholas Negroponte's commentary re: ongoing $100 Laptop for developing nations:

Once children have the laptops, they'll teach themselves, he predicted, making teacher training beside the point. "Teachers teach the kids? Give me a break," he said. "Give any kid an electronic game and the first thing they do is throw away the manual and the second thing they do is use it."

he's right, you know...

The Least Appreciated Mentality

Many of us in the technical communications field approach our work with a chip on our shoulders. The prevailing attitude is that of constantly trying to prove our work's worth. It's the classic: "the manual is important, no really, it is!" sentiment.

Well of course it is, and anyone who says otherwise is a fool. Period, end of story. If you ask any executive or (real) engineering manager what their opinion is of technical documentation, they would probably reply that it’s just one of the necessary steps involved in creating a solid software/hardware product.

But why does the technical communicator live his or her life in constant fear that no one gives a shit about the great documents he or she writes? I have come up with 6 reasons why so many technical writers are defensive about the value of their work. Feel free to add or criticize.

• Unsung hero - It's a certain kind of person who is comfortable with doing a task and not getting much credit. You really need to be of this temperament. After all, the developers of software/hardware are most prominently seen as the primary creators, and even before that it's product management who takes all the credit. I think for this, and so many other analogies, Technical Writers fall into the same category as the QA team. In fact, the TW's role is more visible than a QA person's role in product development. But at the end of the day, both must know to themselves that their work is crucial in delivering that high-quality product.
• False Truth – It’s common to say that no one reads the manual. But, we all know this isn't true. People just don't refer to documentation first. More pointedly, they don't read the manual as they read a book. People refer to the manual for the singular task they need help with. That's all it takes for your writing to return value.
• Low Positive Feedback - What do you want, a cookie? Seriously, no feedback is a good thing. People are more apt to tell you what they think when something is wrong, not when it's right. That's a constant in life actually. If you want positive feedback, go into some customer-service oriented field.
• Content is King - This is a controversial one, but the more specialized the field, the more often it is that the manual does not get the resources or time to include all of the necessary information. TWs put their efforts into things other than the content, like layout and design. The end result is that the information a user requires is missing or insufficient. When problems like this surface, they enforce the notion that the manual is crap.
• Nitpicking Users / High Negative Feedback - Everyone is a critic, and it’s easy for people to attack what's missing and what's wrong. After all, everyone took a composition class in college, so just about ever reader has some basis for critiquing your work. OTOH, you probably can't fire back at a colleague's work because you don't know a thing about RTOS design. It's annoying, and raising the ire of a technical writer often opens the engineer up to a relentless critique of their comma usage in emails and design docs. Don't go down this path :)
• Self Evident software - Since GUI based software is the norm these days, more times than not, it's easy to figure out the basics of an application. For a good number of tasks, documentation isn't quite necessary, it's more of a formality. And since we start at the beginning, our first work is less valued than nailing down the details.

why i can't know everything anymore

I had an idea on the drive home that hints at my answer to Jeff Carr's question, "As technical writers, it seems we too often settle for being generalists. Perhaps we need to specialize more. What do you think??"

I was thinking about my interests in general and how these days it's really hard to keep up with the latest news and ideas about anything. When I was younger, lets mark this at the early days of the WWW, I was into a lot of different things. I still find the same topics interesting to this day: computers, music, technology, hard physical sciences, media, pop culture, the list goes on and on...

I loved to know a lot about a lot.

Fast forward 5-10 years, the present. I find it very hard to keep up with everything today, primarily because of how many people are engaged in the scene surrounding a unique focus. It's not necessarily the huge number of people, but that they are all connected via the Internet. Instantaneous knowledge transfer coupled with access for everyone who wants it is overwhelming us.

Because everyone can easily be an expert, i.e. the price of admission is an Internet connection, and you have to know more knowledge about a focus to feel merely competent, the bar has been raised for entry into the “I know a few things about X, Y, Z club.” Democratization of becoming knowledgeable in a focus also means that you are competing with endless numbers of experts, knowledgeable people, or even neophytes.

So I decided that even though it's hard, I have to reduce my interests these days because the time commitment required to being marginally involved in numerous focus scenes (even as a pure consumer) of information and knowledge would take up more hours of the day than exist. Keep in mind that I am married, and have my first child on the way!

Therefore, I think it is nearly impossible to be a generalist anymore. You could specialize your generality, but now I'm just playing rhetorical games :)

To tie this in, luckily when you go to work, the expectation is that you can handle a single job. But I think if you approach technical writing as a generalist, someone who can work in half a dozen fields, you will usually be passed over because someone out there has invested themselves more fully in a specialization than you have, whether by choice or luck.

In reality of course, a worker is also hired based on price, overall experience, ability to get along with the team, and a host of other criteria that have been around since the cube was invented. BUT, I don't think you should ever underestimate what a deciding factor specialized knowledge is when applying for a job.

I strongly believe that in some ways having a generalist's sense is a highly laudable technical writer attribute, but the speed at which business moves today mostly rewards "hit the ground running" ability over "grow with the company" ability.

comp sci 101

It occurs to me how important it is for a technical writer who works in the software arena to have experience with pseudocode. Not insomuch as you'd actually have to write your documentation with a description of the process in a psuedocode manner, but the advantage is that when you have the basic understanding of how applications step through logic, you're better poised to explain every detail to your audience.

It's fun when you get to piece together and interleave this hard logic with a matter-of-fact tone in your writing.

Technical Writing Rule #24

Just because one Engineer says "it makes sense," doesn't mean it objectively makes sense to all people who understand standard written English.

Alternatively: If the author does not understand why something is accurate, then it's not accurate.

what do you do?

I'd like to post something and see what kind of agreement there is (that is if anyone is reading this).

In my mind, when you actually care, there are 3 discrete technical communication jobs:

• Technical Writer
• Technical Editor
• Documentation [Expert, Specialist, whathaveyou]

Here's my definition of the tasks that fall under the purview of each title:

TW: Culling from design and planning documents, interviewing engineers / developers / marketers, and first hand use of the product, this person creates the documentation that accompanies the product as it goes to market. The technical writer’s main task is similar to the age-old assignment of writing a book report or essay; a topic is researched, learned, and then presented in the best possible format to communicate the issues to the reader. To me, the core value and skill a great technical writer brings to the table is knowing how to tailor a report/paper/procedures for the right audience.

TE: There's so much overlap between a technical writer and editor that the lines are very blurry. Ideally the TE assumes the standard editing functions such as ensuring clear and consistent style, visually, grammatically, mechanically, and substantively. Ideally (again), one can only become a TE after they have spent years as a TW. Only by gaining enough writing experience, would one be at the point where he or she can edit with authority.

On the other hand, it's feasible to understand the topics less than an expert, but still maintain the knowledge required to determine if the needs and style of the documentation is correct.

In a newsroom, you probably don't get to be an editor before you're the reporter. It's the same thing here.

It's my belief that a lot of TWs tend toward the editing side of things.

Documentation Specialist: Technically speaking, a documentation person is mostly concerned with managing documentation. These days, the job encompasses documentation organization, content reusability, and content delivery. This person rarely creates their own documentation; the documentation specialist is somewhat of a content broker.

Someone who is one with Frame maker for instance is a documentation specialist. This person probably spends the majority of their time writing frame scripts, tweaking styles, and setting up EDDs and other XMLy items. He or she has a keen eye for output to .pdf, HTML, or application-based help systems. I had a job once with the title of Documentation Specialist, but really I was a technical writer. In fact, that was a US government DOT contract, and to my knowledge, Uncle Sam knows what a documentation specialist is, but does not know what a technical writer is.

---

There's a very clear delineation between TW/TE and a DS because a documentation person rarely gets his or her hands dirty with content.

In reality one person has to perform all of the above tasks. If we cared, we could title ourselves as technical communicators to indicate we perform all three tasks.

I'm sure that each of us has certain tasks that we really enjoy most and excel at. Certainly though, when technical writers get together and discuss problems, innovations, and other general shop talk, they focus on TE and DS tasks.

Something just clicked...

The internet is filled with people sharing information on how to create and copy highly technical projects. These projects range from programming computers, to physical creations and hacks, like making backyard lightning bolts and putting a home PC in a toaster.

Several of these projects become their own genre (like the aforementioned putting X computer object inside of Y packaging), or taking manufacturer X's hardware, and replacing the software.

If you dig in further, community customs and mores start to appear. What I'm sure many of you have seen, is the classic case of the "noob" (aka newbie) asking for help and explanation. I think that it's kind of vile that so often, these people have to be self-effacing in order to get answers to their beginner questions.

There's a project I've been interested in implementing and completing at home. I've spent several hours researching and learning all the necessary hardware/software/configurations. Yet for all of my Internet searching, I never found a definitive overview of how to complete the project. It’s bullshit that I'd have to make yet another "HI I'M A NEWBIE SO BEAR WITH MY BASIC QUESTIONS" kind of post, especially because this isn't the case. At this point, I know my shit - you could just spell out the process without any details and I'll get it done. Period.

And that's the point where it hit me, that the whole phenomenon of people debasing themselves to learn something can only be blamed on the experts.

By and large, the “experts” can not document a full process clearly; they can only write very specific information in small disjointed parts. I could also place blame on the fact that there rarely seems to be a master editor for so much web-based documentation. This leads to people having a hard time learning the ins and outs of a far-reaching project.

One should be proud to be a newbie, embarking on a project. It is nothing to be ashamed of to ask questions when the teacher did a poor job of explaining something.

(This is of course the argument why books are still relevant when all the raw information is available for free)

clock watching

I have my dream job: working in Internet/networking/telecom field at a start up company that makes a really cool cutting edge product. I've had jobs that sucked before dealing with boring technology, so I'm in a good place right now.

I've always given myself to the idea that you really have to like your work. You sit in an office for 40+ hours a week, and with the driving time, it's almost more than half your life. There are others who just want a steady paycheck so they can make the most of the rest of their lives. and that's fine for them, but I can't understand it personally.

It makes things that much better when you are excited create or learn about your product.

Now of course there are slow times or boring busy work to get through, but when you complain about nearly all your tasks, something is wrong. Change jobs, position yourself to do something you like, but damn it, you're bring me and my kind down!

I always found it a little bit hard when making small talk with people and the topic of their job comes up. I'm a bit embarrassed to chime in "well I actually like going to work, we make a REALLY cool product.” It's just like in school when most kids would proclaim ‘school sucks, I'd rather be out.’ Well, half of the time I liked school!

This is a perennial argument, I know.

So yes, I like technical writing, and documenting software and hardware. And no, I just don’t do this by day.

Now I can’t speak for other fields, and lets keep this to tech stuff, but sometimes I feel that tech writers are especially guilty of not really having their hearts (or at least a portion of their hearts) in the core work of their job-getting some kind of information from a developer’s mind into a customer’s mind.

Some tech writers like the fact that they have a solid white collar paying job, some like to play editor and correct a poor engineer’s grammar (thereby saying nyah – you don’t know that much more than I do), and some like to layout and design documents. But I swear, I think the vast minority of TWs really don’t love the information transferal part of the job. There’s the aspect of the job where we play the content editor and disseminator, and I think few of us are fixated on that task.

YOU CAN'T USE A SEMICOLON THERE!

At this point, I think my blog will explore the same dozen issues over and over. It may run its course and I'll be done with my thoughts after a set amount of time. But lets move on.

On of my biggest gripes about technical writers is the people who are grammar nazis. If you work in tech, or spend any time in any forum online, you know who I’m talking about - the people who get offended at the deepest levels, or act like you just punched their mother if you punctuate a sentence incorrectly.

Now there are some egregious punctuation errors out there. They are funny to read, and sad because the original author is showing off their ignorance. But come on - laugh at the person, shake your head, and then MOVE THE HELL ON.

The number one rule of writing is: if the person reading your prose understood what information you were trying to convey, then the text was a success in its first goal.

I don't understand it, it's like people feel that language is their domain and feel the need to belittle others when their mastery isn't on par. English (or whatever) as a language is freaking amazing in that it still works with highly imprecise input- unlike math or a programming language. IMHO, there are more important things to do with your passion and anger than correct an adult. Children are a different story :)

Believe me, I am a huge fan of terse and precise writing. However, it is not required, nor should it be fought over in realms outside of published textual media.

Good day

and welcome to my blog.

While I have a great life in livejournal, and I just set up a website for my wife and forthcoming baby to discuss all family things, I wanted to keep a separate blog to discuss all things professional. For me, that profession is technical writing, specifically in the IT/software/telecom field.

So I'll rant about that, and the surrounding technologies.

Sounds like a fun time? I sure hope so.