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

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…

Happy Retirement Pat Sweeny!

In a previous life, I was an active member of the West Michigan Shores Chapter of the STC. I met a lot of really cool people there and learned a lot about what it meant to be not just a technical writer, but more about how technical writers can break out of the mold and accomplish things.

One of the people who did that was Pat Sweeny. Pat is (or was, by this point) the President and owner of The Bishop Company, a contract do-it-all house; they document, streamline and illustrate your process, and they do it damn well. Pat was one of the first people in that chapter to "get it", which is to say, he and his company understand that technical writing isn't going to be a department for very much longer, it's going to be a business.

He had the foresight to actually make it a business, but he also had something else. Pat was forever trying to better those around him. He would come to meetings (which was a big step beyond most people) and teach you things. Or he would come to …