Technical Documentation and Editors

Personal Comments Off on Technical Documentation and Editors

For a long time, I was a technical writer. My first gig was with an accounting software company. Whenever you purchase a piece of software, you expect a user manual of some kind, whether on the web, on CD, or a printed version. They had no documentation to speak of, so that’s were I came in.

To write documentation for a product like a mid-range accounting solution, you need to understand how the product works. So I dove in, played with the program for months. Furthermore, I also worked the help-desk, so I got to know the commonly asked questions first-hand. I think I was pretty good at what I did, because once I created some printed manuals, the calls came fewer and further between. If new questions came up with increasing frequency, I addressed them in my next revision of the documentation.

My next job involved writing documentation for a college. It ranged from rearranging Microsoft documentation (since people found it too “cumbersome”) to documenting how to get usernames and passwords.

If you are a writer, you will run into an editor at some point. Whether you write for a newspaper, are a novelist, or a corporate website, you will run into an editor. If you are lucky, you and said editor will see eye to eye. If you are not, you will run into a very common occurrence, an editor with an agenda. Now, the word “agenda” sound ominous, but should not be taken as such. It just is what it is, a preconceived notion of how things should be and an unwillingness to listen to another point of view.

Example: Your editor may be married to a certain word, phrase, or style that may not make sense to your audience. The editor may like a certain phrase because he is comfortable with it. The phrase “focus-free button” does not mean anything to anyone but a programmer. Though a common user may encounter focus-free buttons everyday, the use of the term may confuse the user, in which case, they may find the documentation “cumbersome”.

Sadly, because said editor has the higher position, his word goes. Sometimes, there is no real explanation for the desire to make changes. Personally, I think that some editors just make changes to feel like they have their own personal stamp on the documentation. Maybe it’s just a way to exercise power. Hell, I had one editor make me re-write all my documentation in second person, “just cause”.

Maybe this is why blogs are so popular, a writer’s undiluted thoughts, well at least any filtering is usually their own.

I’m not trying to downplay the importance of editors. A good editor will point out mistakes that you miss (not just incorrect spelling, but style problems), and will also try to enhance your good tendencies. However, some editors forget that they are not only reading the draft in the role of editor, but also in the role of target audience (or purchaser).

Technical writing and its associated editing takes on a pretty weird little role. In my experience, the editor is someone on the technical side, someone used to the jargon common to creators of software or architects of network systems. The intended audience, on the other hand, usually the exact opposite. They are uncomfortable and intimidated by the terminology. In many cases, it can further heighten their insecurity about not being able to function without the documentation (after all, we’re always told how easy everything is on a computer).

So, if on one hand there is an editor with a personal agenda and on the other a nervous reader… Well, you get the picture. Add to this the fact that documentation gets the same amount of attention that junk mail gets, a glance, and disaster ensues.


Politics Comments Off on NAACP

Sometimes, there is a logical jump between a good idea and the actions that follow. Some of the stupidest actions were conceived in the best faith, but when carried out, spectators have to wonder, “What the hell were you thinking? How did you get from there to here?”

On July 9, 2007, the NAACP held a funeral for the N-word. (If I have to tell you what the N-word is, just stop reading now.) A pine casket was brought out, a eulogy was read, and there will be a headstone to mark the side of the burial.

…I’ll give you a moment to let that sink in.

Take a look at the photo gallery.

…take another moment.

The NAACP’s STOP Campaign is a good idea. I agree with their statements and the messages they are promoting. However, when the hell did they go from STOP to a mock funeral for a word? Give me a break. The photos of that funeral are embarrassing. The fact that they dedicated time and money to this is pathetic.

Please don’t misunderstand me. I am not a fan of the N-word in any form. Nevertheless, I really think there might have been a better way to allocate resources, garner press, and/or raise awareness. When an organization does something this ridiculous, it taints everything else they do. In the court of public opinion, there is no forgiveness or forgetfulness. Everything you say or have said will be used against you, always.

Stanley Crouch

Uncategorized Comments Off on Stanley Crouch

Stanley Crouch on Hip-Hop

Rap/Hip-hop only became a huge business when the albums were purchased by white America. Before that, it was underground music. Crouch has referred to hip hop (gangsta rap in particular) as a “minstrel show” on multiple occasions, and over time it has become hard to disagree with him.

Hip-hop videos generally fall into two categories, good and bad. For that matter, most music featuring a black artist fall into the same categories. Bad videos feature expensive luxury cars, big-booty women in tiny bikinis, alcohol in some form or another (sometimes in a jewel-encrusted chalice), gaudy jewelery, and professional sports jerseys. Good videos feature more modest transportation, attractive women in more clothing, earth-toned clothing, and usually a stoop-scene is included in place of a club. While this may only constitute a lack of originality there may be something more.

Are the repeating images of bling, booty-shakin’ and Benzes the product of white America’s desire to see black people making fools of themselves?
Are the repeated images of diamonds, bikini-clad bimbos, and fast cars the only product that young black artists believe will get their video played?

Let’s go back to the “minstrel show” comment. One way blacks were kept out of movies was the rationale that their skin was too dark and thus they would not appear on film (I know, it sounds insane). Once black actors made it onto the silver screen, it was as the butler, maid, ignorant farm boy, etc… While it may be degrading, it was the only job they could get. It the same thing happening with modern rap music?

Crouch’s columns and essays are always provoking. He can be quite the scholar and completely ghetto at the same time. While I don’t agree with every stance he takes, at the very least, he is provoking.

Temporaries Will Always Be Such

Uncategorized Comments Off on Temporaries Will Always Be Such

“You’re doing the job of three people.”
“They’re looking into hiring someone else.”
“Why would they pay two people when they can get away with paying one?”
“Well… I’m sure they’ll give me a raise.”
“Why would they pay you more now when they’ve gotten away with paying you less?”

The conversation above, though paraphrased is one that I’ve had many times, at many different jobs. Odds are, if you are at your desk and dreading the next meeting you have to go to while you are reading this, you’ve either been part of or overheard the preceding lines. It has become part of the reality of the working world (at least in the greater New York area).

When I used to go out for interviews, there were two sets of questions I would always ask. Upon receiving two jobs, I was told that the people interviewing me said that these questions showed I was “on the ball”.

1. I know that the job is 9am to 5pm, but what are the average leaving time? Is there a particularly busy season in which I will have to put in a lot of overtime?
2. What are some of the things I will be responsible for that aren’t necessarily in my job description? Though my title will fall under Department A, is there another department that I will have to answer to/work closely with?

Would you ever pay someone more if you could get a job of the same value for less? Of course not. When I read an article on temps today in the New York Daily News, I had to shake my head. Why the hell would any company hire a permanent person when they can get the same job out of a temp? To save on the commission cost to the temp agency.
To keep a quality person in the position.

Let’s just run some quick numbers. (Keep in mind, the numbers below are what the company will pay.) The NYDN said that one gentleman stood to make $17 per hour.

$17 per hour
8 hour day: $136.00
40 hour week: $680.00
1 month: $2720.00
1 year: $35,360.00

Now imagine that they are paying the temp agency a 20% commission. I would be surprised if this was an average percentage, but for the sake of argument, let’s go with it.

With 20% commission $17 per hour becomes $20.40 per hour
8 hour day: $163.20
40 hour week: $816.00
1 month: $3264.00
1 year: $42,432.00

So far, this makes sense. Without commission, the company can save $7072.00 per year. This is assuming that this person is needed all year and not just on a project basis (imagine 8 months per year). However, if you go for a full time job, you’re probably going to want health insurance. Here are some averages I got from The National Coalition on Health Care:

Average cost per single coverage: $4200
Average cost per family of four: $11,500

Finding the average employee contribution to their health plan was a little harder to track down, so I took an example from a major city, Boston. For the sake of argument, we’ll say the single person contributes 3.5% (a rough average of the “between 1.5 and 6.6 percent” mentioned). Based on our $17 per hour full time hire, let’s take a look a what the company will pay.

$39,560.00 single; $46,860.00 family
Payment less employee contribution: $39,413.00 single; $46,457.50 family

If this guy does not have a family, the company can still save a few bucks by hiring him full time. Then again we did not take into account retirement plans, severance packages, unemployment payments (if terminated), etc…

Tell me, “Why a company would hire a temp to a full-time position?”