Skip to main content
News

What do Tech Writers Want?

Answer? I don’t know, but The Content Wrangler is conducting a survey to find out. Here’s the announcement:

2009 is a touch economic year for most of us. Companies are cutting back on nice-to-have purchases and focusing in on what’s necessary. This survey conducted by The Content Wrangler aims to help us better understand your training needs for 2009 and to identify the types of classes you need. We plan to use this information to help training providers create relevant public and on-site training programs that address your needs and to gain an understanding of the current state of training program interest in our industry today.

In case you need further motivation, there is also a random drawing for some goodies. The survey has only five questions, so it should be quick.

Take the survey

Sarah O'Keefe
March 26, 2009
Read More
Conferences

Life in the desert

Last week, I attended the annual DocTrain West event, which was held this year in Palm Springs, California.

Weather in Palm Springs was spectacular as always with highs in the 80s during the day. Some of my more northerly friends seemed a bit shell-shocked by the sudden change from snow and slush to sun and sand. (North Carolina was 40 degrees when I left, so that was a nice change for me as well.)

Scott Abel did his usual fine job of organizing and somehow being omnipresent.

I promised to post my session slides. The closing keynote was mostly images and is probably not that useful without audio, so I’m going to point you to an article that covers similar ground (What do Movable Type and XML Have in Common, PDF link).

I have embedded the slides from my DITA to PDF session below.

Demystifying DITA to PDF Publishing

View more presentations from Scriptorium.

I have also posted the InDesign template file and the XSL we built to preprocess the DITA XML into something that InDesign likes on our wiki. Note that running the XSL requires a working configuration of the DITA Open Toolkit. For more information, refer to the DITA to InDesign page on our wiki.

Sarah O'Keefe
March 23, 2009
Read More
News

How to Get a Job

[update to correct bad links]

This is the best advice for job seekers I’ve ever seen. India Amos writes about her pile of resumes:

And do you want to know what’s the most striking thing about most of these hopefuls? They are completely wasting their time. And mine, of course, but mostly their own. Because they’re not only not going to get a job with me, they’re not going to get a job with anyone unless that person is as slovenly and illiterate as these applicants.

She proceeds to offer some excellent advice in numerous categories. Here are some excerpts from a lengthy list about formatting:

  • Learn to use style sheets, so that you can make your heading styles consistent. If you choose to ignore my request for a PDF résumé, try to make sure your Word attachment doesn’t demonstrate to me what a slob you are, formatting everything locally and aligning text using spaces instead of tabs.
  • Don’t Capitalize Everything. I Cannot Emphasize This Enough. It Makes You Look Like a 419 Scammer.
  • Violet 9pt Arial is probably not a good choice for anything.

Hehe. (sob)

Related to this: How Not to Get a Job (Palimpsest, December 2007)

Of course, in today’s economy, lots of people need jobs. So here is some long-promised advice on how to get a job:

  1. Apply for jobs where your skillset is relevant. In this job market, with tons of job seekers, you are unlikely to get the “stretch” position. So, look for positions that are equivalent to your last position, that you are uniquely qualified for, or that you are slightly overqualified for. For instance, let’s say you are a technical writer with five years of experience and “the usual” complement of technical skills. What is your unique qualification? If you speak some Japanese, look for Japanese companies where your language skills might be useful. If your undergraduate degree is in music, look for a company that makes music software or products related to music. In other words, look for a position where your outside interests are also relevant. But, at a minimum, apply only for positions that you are reasonably qualified for. It’s tempting, especially when you really need a job Right Now, to take the firehose approach and spray resumes everywhere. It doesn’t work. Focus your job search and send out a smaller number of really good applications.
  2. Do your homework. Before contacting the company, investigate. Read their web site, read any recent news coverage. Look them up on LinkedIn and see if you know anyone in the organization. (You are on LinkedIn, right?) Use the information you find to make your application more relevant. If you get an interview, do more homework before the interview.
  3. When you apply for the job, follow the #!%$#!%#! instructions. If asked for PDF, provide PDF. If asked for Word, provide Word. Et cetera.
  4. Submit resumes online. Paper and snail mail takes too long. By the time your resume arrives by mail, the position could be filled. Also, dropping off your resume in person? Creepy and needy. (One exception: If you know someone at the organization and they are willing to deliver the resume for you. Even then, I would recommend sending your contact email with the resume and asking him or her to forward it.)
  5. Whether it is requested or not, write a cover letter. The cover letter should be the body of your email and not an attachment. Follow Ms. Amos’s excellent advice. You might also use a T letter as your cover letter, but do send the resume. Tom Murrell describes the T letter in detail in his article Get More Interviews with a T-letter. But again, I disagree with his advice to leave out the resume. If you are instructed to send a resume, send a resume.
  6. Show up on time for any in-person interview. If possible, do a dry run the day before to locate the building. Or plan to arrive very early. There are worse things than sitting in a nearby coffee shop for half an hour. (Don’t chug too much coffee.)

I could go on for a long time, but frankly, these six points will lift you above 95 percent of the other applicants, and you can do the rest.

(India Amos via words / myth / ampersand & virgule)

Sarah O'Keefe
March 9, 2009
Read More
Opinion

I am not a Pod Person

Confession time: I don’t like podcasts.

And I think I know why.

I am a voracious reader. And by voracious, I mean that I often cook with a stirring spoon in one hand and a book in the other. I go through at least a dozen books a months (booksfree is my friend).

So why don’t I like podcasts?

  1. They’re inconvenient. I don’t have a lot of interrupted listening time, other than at the gym. And frankly, there’s a bizarre cognitive dissonance listening to Tom Johnson interview Bogo Vatovec while I’m lifting weights. I tried listening to a crafting podcast, but that was worse — my brain can’t handle auditory input describing crocheting techniques while simultaneously operating an elliptical machine. So I went back to Dr. Phil on the gym TV. It may rot my brain, but at least it doesn’t hurt.
  2. They’re inefficient. I can listen to a 30-minute podcast, or I can skim the equivalent text in 90 seconds.

I’ve been thinking about what would make a podcast more appealing to me, and realized that it’s not really the medium I object to, it’s my inability to control the delivery.

I’ll become a podcasting proponent when I perceive these properties:

  1. Better navigation. Podcasts, like other content, need to be divided into logical chunks. These chunks should be accessible via a table of contents and an index.
  2. Ability to skim. Podcasts need to provide the audio equivalent of flipping pages in a book or scrolling through a document while only reading the headings.

Depending on the software you use to consume podcasts, you may already have some of the features. For instance, a colleague told me that he listened to my recent DITA webinar at five times the normal speed:

I wanted to let you know about something in particular. I listened to it at 5x fast fwd in Windows Media Player while drinking a coke. My heart is still racing. You should try it. :o)

Do you enjoy podcasts? Do you have any special techniques for managing them efficiently?

Sarah O'Keefe
February 27, 2009
Read More
Opinion

DITA isn’t magic

The WritePoint staff blog makes a very good point about DITA: it isn’t a magic wand that fixes documentation problems. Also, it’s worth noting that:

… DITA didn’t introduce something completely new. DITA incorporates achievements made in a wide variety of approaches to organizing content that were being proactively conducted starting from 1960’s.

Don’t get me wrong: DITA can be a good solution for many departments that want to set up an XML-based single-sourcing environment. Just don’t expect that a twitch of your nose will convert your legacy content or make the output from the Open Toolkit match your formatting requirements.

Alan Pringle
February 25, 2009
Read More
Tools

Don’t type, drag to the cmd window

I spend a good deal of time with a Windows cmd.exe window open on my desktop. If I’m not running the DITA OT, I’m testing some Perl script, or Ant, or Python, or who knows.

A few years ago (in the Windows 98 days), I discovered a nifty cmd window trick. People are consistently amazed when I demonstrate it to them. Now I’m going to share it with you.

Say you need to change directory to some long and gnarly path name. You could type the whole thing in. Or, if you have Windows Explorer open on your desktop, you can:

  1. Type “cd ” in the cmd window (the space is important).
  2. Go to Windows Explorer and find the folder you want to navigate to.
  3. Drag and drop the folder from Windows Explorer to the cmd window.

Hey presto! The path name is copied to the cmd window. What’s more, if there are spaces in the path, the path is automatically quoted.

Now you can click in the cmd window and press Enter to perform the command.

Cool! No more typing long path names for this ToolSmith.

This works for filenames too. If I’m running a Perl script that needs to work on a file way down my directory tree, I type “perl myScriptName.pl “, then drag and drop the file name from Windows Explorer into my cmd window.

I’ll keep adding more ToolSmith’s Tricks as I use them. What’s your favorite trick?

Simon Bate
February 20, 2009
Read More
Tools

WMF…that’ll shut ’em up

Which graphics formats should you use in your documentation? For print, the traditional advice is EPS for line drawings and TIFF for screen captures and photographs. That’s still good advice. These days, you might choose PDF and PNG for the same purposes. There are caveats for each of these formats, but in general, these are excellent choices.

Of course, everybody knows to stay away from WMF, the Windows Metafile Format. WMF doesn’t handle gradients, can’t have more than 256 colors, and refuses to play nice with anything other than Windows.

Think you’re too good to hang out with WMF? For your print and online documentation, perhaps. But it may be a great choice to give to your company’s PowerPoint users.

Are you familiar with this scenario? PowerPoint User saw some graphics in your documentation and thought they would work for some sales presentations. The screen captures are easy; you just give PowerPoint User PNGs or BMPs or whatever. It’s the line drawings that are the problem. PowerPoint User doesn’t have Illustrator and has never heard of EPS. PowerPoint User says, “Can you give me a copy of those pictures in a format that I can use in PowerPoint? Oh, and can make that box purple and change that font for me first? And move that line just a little bit? And make that line thicker? And remove that entire right side of the picture and split it into two pictures?”

You want PowerPoint User to reuse the graphics; you’re all about reuse. But you have dealt with PowerPoint User before, and you know you will never get your real job done if you get pulled into the sucking vortex of PowerPoint User’s endless requests.

The secret is to give PowerPoint User the graphics in a format that can be edited from within PowerPoint (or Word): WMF. Here’s the drill that will make you a hero:

  1. Save your graphics as WMF.
  2. Place each WMF on a separate page in a PowerPoint or Word file.
  3. Tell PowerPoint User to double-click on a graphic to make it editable.(If you think your PowerPoint User is really dumb, you can double-click the graphic and respond to the dialog box asking if you want to make the drawing editable yourself before saving the file, but nobody is that dumb.)

WMF. It will make PowerPoint User go away…happy!

Sarah O'Keefe
February 20, 2009
Read More
Reviews

Review of screen capture programs

by Sheila Loring

Matthew Ellison reviews seven screen capture programs: FullShot, HyperSnap, SnagIt, Madcap Capture, RoboScreen Capture, ScreenHunter (free), and TNT. He also points out what to look for in a screen capture tool and compares features in a handy table.

http://www.writersua.com/articles/capturetools/index.html

SnagIt lands at the top of the bunch. Matthew describes it as “the most full-featured of the capture tools reviewed in this article.”

I’m a recent SnagIt convert after using Paint Shop Pro for years. SnagIt can’t be beat for a quick, easy screen shot. I also like the torn edge options to indicate a partial shot of the GUI. But the jagged edges might be more of a creative device than helpful visual cue. What do you think?


ScriptoriumTech
February 17, 2009
Read More
Conferences

Upcoming DITA events (free, cheap, and discounted)

Free

Tomorrow (February 5) at noon Eastern time, I’m doing a webinar, DITA 101–Why the Buzz?

This is a basic introduction to the Darwin Information Typing Architecture, an XML standard for technical communication content. If you’re wondering about this DITA “thing,” and want to get some basic information, this is the session for you.

Also, the price is right, as it’s free (register here). Audio will be Internet-based, so you don’t even have the expense of a phone call.

Many thanks to MadCap Software, who is organizing and sponsoring this series of free webinars. These sessions are “tool-independent” — they are not going to be pitches for MadCap products.

Cheap

I have to mention Simon Bate’s new Hacking the DITA OT white paper again. It’s crammed with useful tips and tricks on how to get started configuring DITA output to your satisfaction. It’s not free, but at $20 for an instant download, it’s pretty cheap.

Discounted

Conferences are more expensive than our $20 white paper, but they also give you the opportunity to talk with people face-to-face. My next conference event is DocTrain West (Palm Springs, CA). I have two sessions:

  • What Gutenberg Can Teach Us about XML: This session looks at movable type and explores how the changes introduced by the printing press compare to the changes introduced by XML.
  • Demystifying DITA to PDF Publishing: This session discusses the advantages and disadvantages of each approach to extracting PDF from DITA content. Includes discussion of the DITA Open Toolkit, FrameMaker, and InDesign.

You can register for the event at a $400 savings until February 17. I hope to see you there.

Sarah O'Keefe
February 4, 2009
Read More