Skip to main content

Hand to forehead moment

This hand slap to the head once again brought to you by Technical Writers. Someone with the title Technical Author (cue eye roll) posted a one sentence question to a Help-authoring tool list. To quote: "Can anyone tell me what 'structured authoring' is?". This was met by links to a Google-searched PDF. The person read about, oh, 7 words, then skimmed and then came back to the list with (paraphrasing) "So, it's using templates?".

Cue hand to forehead.

Ok, this message is for all you Technical Authors, Content Developers, User Assistance Engineers, and plain ole' Technical Writers. (The rest of you can leave if you want.)

You. Are. Not. Helping. In the immortal words of Jon Stewart, "Just stop." If the following phrases don't mean anything to you, start polishing your resume:

  • Content Management

  • Information Architecture

  • Metadata

  • Business Objects

  • Format separated from Content

  • Assembling documentation (and not in a binder)

And I swear to God if any one of you mentions that XML will solve your documentation issues (such as short timelines and content management) and you don't have the first clue about how to accomplish those goals in the absence of a consultant, I'm going to really lose it.

I appreciate the communities that exist out there for authors, I really do. There are some really good ones. But, and I mean this in the most abrasive way you can imagine, some of the people that come there are so damn clueless, there needs to be an official person who virtually (or literally) clubs them over the head when they ask dumb questions. Google is your friend. If that doesn't work, at least think about what you're going to ask. No one hands you information anymore, and as a documentation person, you should know that first hand.

After that, post away but at least put something there for people to react to. Don't come like a child with your hand out asking for an M&M; put some damned effort into it. I know you've had that job for like 20 years and don't want to change, but too bad. I wrote for less than 5 years and I had to change more than once; it's the new way of the world.

Actually, it's not, it's the way business has been for a very long time, you just haven't had to work in a business environment because you've been treated like a cost, a necessary cost of doing business. It is in the interest of anyone who wants to keep writing to make themselves valuable. If you don't, you'll find out quickly what happens if you aren't.


Popular posts from this blog

RIP Tom Petty

Tom Petty died today, aged 66. I won't claim to be a huge Tom Petty fan, but I've bought an album or two and sang along in the car to one of those songs everyone knows. I'll  stream a lot of his catalog today to remember the songs I've heard once or hundreds of times.

I also owe Petty credit for a singular moment in my life, and one I never expected to last in my mind.

Nearly 20 years ago, I was a fresh-ish faced transplant to Ann Arbor, MI by way of my first "real job" out of college, working for a software company in Dexter. I was renting a house with some other folks who'd also been displaced as a result of a fire at my first apartment. I was the only family member East of Lansing, which made me a contact point for anyone going through Detroit Metro airport.

Which is how my uncle Dean came to spend a few hours with me one evening. At the time, my grandparents (his parents) were wintering in Texas. My grandfather had health problems most of his life and…

Google Inbox: A classic Google product

My work domain (an EDU) recently had Google Inbox enabled so I had a good chance to try it out. My personal email is relatively quiet and, I believe, doesn't provide a good Inbox experience. Work is more active and requires actual management, something I've tossed many a tool at over the years. As part of my work life, I supported the Google Apps for EDU installation here and took a pretty extensive presentation to campus about how to manage large amounts of email.

Inbox is a classic Google product: the distillation of a number of excellent ideas into a set of half-complete features built for a use case most people don't meet. We've seen this in the past in products like ChromeVox, Google's Chrome extension for accessibility. ChromeVox works great on ChromeOS devices, but completely ignores the point that most users of accessibility tech (AT) don't have or want ChromeOS devices and come to services with their AT in tow. ChromeVox also ignores decades of convent…


Evernote, for better or worse, is the best note-taking service for my needs. It works across all my devices/computers/modes. It's fairly easy to get stuff into it. Hell, they even have 2-Factor authentication. The Windows app is a little clunky and my girlfriend and I have never been able to get shared notes to work properly (conflicted note! three times in the same grocery trip!), but what service is perfect? At least they have nice socks.

Everything, in fact, is pretty good as long as you don't screw up. And screw up I did. I'm not very regular about making backups, but I do make them every month or so. Once you figure out how to create a backup, that is.

There's a helpful Export Note option (which turns into Export Notes when you select multiple notes HINT). The export process is essentially opening All Notes, selecting every note, and then choosing Export Notes. Or something like that; Evernote never tells you, you're left to figure it out on your own. The file…