Wednesday, October 08, 2008


Some of you know that I'm a technical writer. I'm on the mailing list of my local chapter of the Society for Technical Communication - never mind that I don't belong to the STC these days, have quit a few years back after being driven mad by extremely unprofessional communications from them.

One example: The organization set up a bunch of mailing lists for particular interests, then didn't bother to train the moderators in how to run an Internet mailing list, how to handle the mailing list members, etc.

I remember seeing email in all capital letters. C'mon: if you're a technical writer, you should know where the caps lock key is.

I remember seeing email asking how to unsubscribe; the mailing lists were set up using listserv, and each email had a footer giving the basic commands for subscribe/unsubscribe. C'mon: if you're a technical writer, you should know how to RTFM. (Even if you don't know those listserv commands by heart, which I do.)

I remember seeing email asking why the user was receiving email from the list. C'mon: you asked to be subscribed.

At least, I did. But I got off that mailing list fast, because neither the users nor the moderator knew what they were doing, a very bad sign among ostensible technical writers, who should have known the etiquette and use of Internet mailing lists by, oh, 2000 or 2001, when all of this happened.

Anyway, today's email from the local STC chapter pointed to the chapter newsletter, which is on their web site.

I took a look. You could say I have a few beefs with what I found.
  • The newsletter is posted as a PDF, a notably unfriendly format on the Web.
  • I'm just guessing that the newsletter is published with FrameMaker, the technical writer's best friend. You can create HTML with FrameMaker, using a program called WebWorks. For that matter, you can create HTML with Word (crappy though the HTML will be) and with Arbortext Epic. Or someone the STC might know Dreamweaver.
  • There's an article in the newsletter on web usability! I had to laugh, considering the PDF.
  • Apparently it is the most recent article in a series, but you can only tell by reading the article. It's not labeled 3 of 5 or Part III.
  • The capitalization of that article's title is eccentric: "Web usability" is on one line, "How Not To Do It" is on the next. There is no style guide in the world that recommends capitalizing "to" in a header, or putting half a title in sentence case and the other in title case. (Shoot me now: I hate sentence case in headers.)
  • There are lots of URLs in that article. None of them are live. PEOPLE! You can put live URLs in a PDF!! Don't you know anything about Acrobat???
  • Oh, wait! They ARE live links. It's just that they're the same color as the running text, so you have to guess that they're live.
On the positive side, the article does point to one hilariously bad web site, about which the author says "If I wanted to play Myst...."


Michael said...

Oh. My. God. I followed that link. There's five minutes I'll never get back.

I love that they found a way to simulate in a web browser the experience of waiting for an elevator. Any of that Macarthur genius money left over, I wonder?

That site is clearly designed to ensure that visitors will not get any information about the company, so in that regard it's a success.

calimac said...

Death to all websites that automatically play sound files. Sound files should be separate embedded files, identified as such, and played only at the user's explicit option.

Paul H. Muller said...

In my day job I am in technical sales and I remember when we first went on the web about 12 years ago. I did all the HTML pages in a program called DIDA (freeware, I still use it) that was just slightly more sophisticated than doing HTML in Notepad. I learned all of the standard tags and did all of the pages myself.

And I am really good at creating a bunches of generic web pages. I was convinced that HTML was going to take over the world and was surprised when Adobe .pdf became more or less standard for product data sheets.

I think the reason is that .pdf pages can be printed out and they look exactly like fancy printed data sheets. So someone wants your product, they ask for a quote, print out the .pdf data sheets and staple the whole thing together with a requisition and send to purchasing. We sell lots of stuff this way.

The .pdf format, being just like the printed page, is familiar visual terrain and our customers put more credibility into a .pdf file than the equivalent information in an HTML page. The high bandwidth of the printed page, and its layout and customs, are still more persuasive than web pages. We wound up putting all 125sets of product data sheets, instruction manuals and price lists into .pdf.

But I think that is slowly changing - I was just ahead of my time.

I have tried printing my scores in .pdf but have had really terrible luck printing them out - the staff lines sometimes go just bonkers and I have no idea why.

Adobe .pdf leaves a lot to be desired, but it has become a defacto standard. Sorry for the rant, but I couldn't resist a trip down HTML memory lane...

Lisa Hirsch said...

Michael, yeah. It's ludicrous. Maybe the guy should just be a game designer.

David, yes, I agree.

Paul, rants always welcome. :)

PDF is great for lots of things, like distributing long technical documents. By that I mean anything that would run more than, say, five pages printed out. By and large, technical users like hard copy, and printing HTML is a pain.

But the STC newsletter is quite short, maybe 5 or 10 pages. A lot of the stuff is boilerplate, like reports on meetings of various kinds. If you're distributing that material only on the web, it doesn't need to be in a "newsletter;" it can be on a different part of the site devoted to meeting minutes. The articles belong in HTML.

Richard Mateosian said...

Hi, Lisa -

Long time no see. I'm glad you haven't lost your edge.

I didn't know about your blog, but somebody sent me a link to your critique of the Berkeley chapter newsletter. I'll take responsibility for PDF. We had changed to HTML for a few years, and I made sure we changed back. I wanted a format that we could archive and print easily. I'm not sure where that usability article came from or why the links are not live, but I'll pass all of the complaints to our editor.

Take a good look at the rest of the newsletter and some of the other issues. They're actually pretty good.

And come to a meeting one of these days. We've had a lot of good ones in the last year or so.

Lisa Hirsch said...

Hey, Richard! How are you? Where are you working these days?

I thought I shamelessly promoted the blog when we were working together, but I guess not! Mostly, it's about music.

The links are live - see my last bullet in the blog posting. You just can't tell unless you take a flyer and click one of them.

Printing HTML is a pain in the neck, for sure, but PDF is a lousy web medium. Making the newsletter available in both formats available would be ideal.

Richard Mateosian said...

Hi, Lisa -

I have always said it would be great to publish both HTML and PDF, and I think that's pretty easy with FrameMaker (and WebWorks before Frame 8), but every newsletter editor I've discussed this with says it's too much trouble. If you delegate a task to someone, you have to trust their judgment most of the time.

We can catch up offline about what's going on in our lives.