Angry documentation...

So.... this week at work, a lot of my time was taken up fixing "angry documentation."

What the hell is that?

Ok. Technical writers can, and will, debate at length not just about grammar subjects, but about the particular connotations of language and a zillion other things that would bore most others to tears. In a not-related-to-my-main-subject-but-it-happened-at-work conversation this week was someone asking a "is this proper grammar?" question, where my big point was "Well, yes, that is, but it is also odd and easily misunderstood."

Odd and easily misunderstood.

What do I do as I am typing this? What is it I do to the keys?

First answer is usually "hit". Hit the keys. Well, I'm not attacking them with the full force of a hit. It's usually a bad idea to suggest the word "hit" when dealing with people frustraited with delicate and expensive technical equipment, too. Those are just a coupla reasons why "press" is the preferred term. You press keyboard keys.

When I go to the "Publish Post" button to send this live to the interwebs, what am I doing then? Press? Kinda but not really. Hit? Again, violence toward unarmed computer equipment is kinda mean. I will be using my mouse on that button. What does a mouse do? It clicks. Click click click click click away. So, a mouse action is usually "click the blah blah blah button."

A very nice thing about having two terms, "press" and "click", is that it is easy to tell if you should be doing something on the keyboard or with your mouse. Style guides detailed this all for us YEARS ago.

But, usually when stuff is submitted to us writer-types, it's full of "hit" and lots of misuse.

And unless you are under a super tight deadline, this is something that you tend to clean up first thing before sending stuff live onto the interwebs.

But, when a writer was utterly swamped to get critical info into a doc and it was mostly written in pretty clear instructions, sometimes you just close your eyes, wince, send it out, and hope it doesn't come back to bite you in the ass.

This week, someone submitted a work request to fix a couple issues in a coupla documents. When I went in, I found a zillion and a half other errors looking back at me. Sigh. Thankfully, we're not super-overloaded right now so there was time to go in and clean this stuff up (in the three places it needs to be done). Bye-bye, angry documention that encourages violence.... hello, friendlier and more easily understood documentation.

It's not curing cancer or dealing poker to high rollers, but it pays the bills. And in my happy fantasy land, it's got to make this stuff easier to understand to at least ONE person.

In other news.... went to Home Depot tonight and we bought our new vanity, vanity top, faucet, bath fixtures, towel rod, plumbing stuff and other goodies to get us to the point of a 90% done bathroom this weekend. After work this week I went and got a new "crescent" shower rod and bath caddy. Wooo. I might actually hit a store tomorrow to see if I can find some cute, new towels to hang when we get the towel bar up. Exciting, huh???

Tech Writing Fun

As a tech writer... you often get to see some funny stuff. Like, at the old job, Russian text that when ran thru a web translator gave back text about submitting to the "interactive regime". That had me laughing for a week.

Saw two gems today.....

One document that is normally not run by tech writers for approval, that mentioned the "forward slash" and the "other slash". What... like the one from Guns'n'Roses???

In some source material I was editing today, I found a lot of appearances of "Therefore for example". It's not uncommon for people who are intelligent but uncomfortable with writing to get ten kindsa bad-uber-formal when they put stuff on paper. Very preachy and talking down to the reader. It's expected, but it can still be amusing.