Thursday, August 7, 2008

MadCap Flare, the help author's dream tool

Ok, it's been a while since I wrote last. I've had a hectic Spring and Summer. I switched jobs, got married, learned a brand new software product, and helped my wife complete an absolutely insane summer course schedule (she had class and work from 7AM-9PM every day, then studied until 1AM... every single day). Thus, the blog sort of fell by the wayside.

I'm back, though! And I'm ready to share some new insights with you. First, I'd like to talk a little about MadCap Flare, the new software I began using a little over a month ago. It's really top-notch. I've lucked into a great situation here at my new job, since I'm the first (and currently only) technical writer. So, I got to pick the software program I wanted to use. After a week of serious comparisons, I chose Flare. My only concern was the learning curve; I had less than a month to learn the software and use it to write and develop an entire online help system for a new product.

Fortunately, Flare is very easy to use. It took me less than a day to learn my way around the interface and to begin authoring some rudimentary help topics. As time went by, I incorporated more and more complex stuff into my topics. Recently, I even began playing around with DIV tags, which are very powerful. Now, let me say that I'm no CSS expert, but Flare makes all of these things relatively easy!

Here's what my site currently looks like:

Of course, you don't need to get fancy. If all you want to do is create some basic text topics and organize them in a WebHelp project, complete with Search capability and a Table of Contents, you can be up and running in no time.

One of the other bright spots about Flare is the support. When I was comparing products, I downloaded a trial copy of Flare (the output is gibberish). A MadCap sales rep contacted me almost immediately and answered all of my questions. She even was willing to work with me on the price, since our smaller company cannot yet afford to shell out huge bucks for software. As I learned to use the software, I found the MadCap support forums to be invaluable. Most of the time, the MVPs there respond faster to my posts than the MadCap support reps respond to my e-mails (I got the 'free email support for a year' package, mainly so I could get a free upgrade to Flare 4.0, which comes out later this summer).

All in all, it's been a great experience, and my help files look great! Flare let me focus on the content instead of worrying about the framework and tweaking the look of every little thing.

Want to learn more? Here are two of the most helpful articles I found. Paul Pehrson is one of the MadCap MVPs who are so helpful on the forums, by the way.

45 Things I Love About Flare, 31 Things I Hate About It
- Tom Johnson on his blog, I'd Rather Be Writing
http://www.idratherbewriting.com/2008/01/31/45-things-i-love-about-flare-31-things-i-hate-about-it/

Six Reasons to Love Flare
- Paul Pehrson on his blog, Technically Speaking
http://blog.paulpehrson.com/2007/06/18/six-resons-to-love-flare/

If you like what you've heard, try it out!

MadCap Flare trial download site
http://www.madcapsoftware.com/products/flare/

Tuesday, February 26, 2008

Helping SMEs and reviewers help you

One of the issues we need to guard against is excessive confidence in our own ability. In the past, when managers asked me to estimate a completion time for a project, I almost inevitably came up with a "best case" scenario with very little margin for error. Plus, I usually failed to consider a very important fact when I mentally calculated the time: I need to rely on others for timely information and reviews! How to combat such a mistake? Learn to help others help you!

That's right. Sadly, we can't do it all by ourselves. However, I have found that persistent (but gentle; we need to work with these folks in the future, remember) pressure helps subject-matter experts (SMEs) and reviewers deliver on time. Also, give deadlines for them! Explain when you need to finish the chapter (or document or whatever unit you're working on) and how much time you'll need to make revisions and conduct any further reviews. Most people will understand and, so long as you give them more than a day or two, will work to help you meet your deadline. Just remember that your job isn't in the forefront of their minds, so reminders do not hurt.

As I said, though, be gentle. "Hi! Just wanted to remind you that I need the XX review by the end of tomorrow. Let me know if you have any questions, and thanks again!" is much better than, "Finish the review by tomorrow at 5PM and place it on my desk." Persistent, polite requests are a lot better than demands. If you can tack the reminder onto another request, so much the better, because you won't seem quite so naggy!

Even better, go see the person! E-mails are easy to ignore (or to set aside for later reading... which might or might not happen!). However, in-person reminders are impossible to ignore. Plus, if the SME/reviewer knows that you'll be back and they'll need to look you in the eye and explain why it's not done, they're more likely to do it. If in-person meetings aren't possible, phone calls are good, too.

Let's summarize the tips to help SMEs and reviewers get stuff to you on-time:
  • Be very clear about what you need from them and ask them to confirm that they understand. Sometimes they might not look at it right away, and you don't want to waste valuable time explaining the task when it's getting close to the deadline.
  • Give them more than a day or two. I usually give between 3 and 5 business days.
  • Persistently, but gently, remind them (and ask if they need any information from you) as their deadline approaches. If possible, attach the reminder to another request.
  • Go see them in-person to explain the task and to remind them to complete it. It's difficult to ignore people when they're right in front of you.
Good luck! Create good relationships with your SMEs and reviewers and help them learn to help you, and you'll be poised to demolish your deadlines!

Thursday, January 10, 2008

Charlie Kaufman's Adaptation, a tribute to the pain of writing (movie review)

I was watching one of my favorite movies the other night, Charlie Kaufman's Adaptation, and it got me thinking about how all writers share a common bond. We all work to please an audience (except poets... pphht selfish). We (almost) all need to do research. We all know the joy/pain of searching for exactly the right word or phrase. This movie shows the pain of writing in exquisitely horrible detail. It's wonderful.

So, I decided to write an impromptu movie review of it. It’s long and doesn’t have a lot to do with technical writing, but hey, it’s my blog, after all!

Anyone who knows Kaufman knows that he excels at writing twisted, hard-to-follow plots that are as fascinating as they are confusing. In fact, it's almost exhilarating when you finally figure out what the heck is going on! Adaptation is no exception.

The plot centers on Kaufman himself, as he tries to write an adaptation of the book The Orchid Thief, by Susan Orlean (real book and real person, I looked it up). This book is about the beauty of flowers, and Charlie decides he wants to show that beauty in his movie without contrived plot elements. He describes this decision during a crucial scene with a producer early in the movie... pay attention! It'll add a lot to your enjoyment of the movie later on, heh.

Meanwhile, his live-in twin brother, Donald, is taking a screen-writing seminar, which Charlie initially despises as a money-grabbing gimmick, but which later proves his salvation of sorts. Donald (who's none too bright) is also writing his own screenplay, called The 3. This movie is about a killer who kidnaps a girl and slowly dismembers her, while a cop tries frantically to track them down. The catch? All three people are in the head of one person... multiple personalities! "How," Charlie asks, "do you write a movie where the main character is in a police station and is, at the same time, being dismembered in a basement?" An excellent question, but not one that worries Donald, whose amazingly umm... interesting ideas include a car chase scene where the cop follows the killer on horseback. "It's, like, technology versus horse," Donald patiently explains to an incredulous Charlie.

All this sounds pretty simple, right? It isn't!


Stop reading now if you haven't seen this movie yet. Then, go rent it (don't buy it; it's a great movie but you probably won't want to watch it more than once a year or so). Then, watch it. Then, come back here and continue reading!

Charlie has a LOT of trouble deciding how to adapt the book. It's a book about the beauty of flowers, yet nothing really happens in it. How to write an engaging movie about such a book? It doesn't help that Charlie's personal life is a complete mess. His self-confidence is shot. He's scared of talking to any pretty girl. He fantasizes about every woman he meets and masturbates constantly. He derides himself as fat, bald, untalented, lazy... the list goes on and on (and on). He's in love with a woman who obviously likes him, but whom he can't even get the courage to kiss when frequent opportunities present themselves. And, to top everything off, he learns that Donald's screenplay is being purchased... for a million dollars!

As he writes his screenplay, we are transported to Orlean’s autobiographical experiences as she meets the orchid thief himself and learns about the passions of orchid collectors. Indeed, the book isn't so much about orchids as it is about passion itself... Orlean longs to feel passionate about something, anything, the way these people feel about orchids. But is that a movie? Charlie can't figure out a way to make it one.

Then, the movie really gets interesting. As we follows Charlie's struggles to write his script, we slowly begin to realize he's writing the script for THIS movie! Oh, what a convoluted, circular, wonderfully incomprehensible concept! We experience his manic retelling of this entire movie to that point, right up to the spot where he's retelling his RETELLING. But how to end such a movie?

Enter Donald! At his urging, Charlie goes to New York to meet Susan Orlean, but he chickens out when he enters her work building and sees her in the elevator. Donald tells him that his screenwriting instructor, Robert McKee, is in NYC for a special seminar, so Charlie, in desperation, goes and pitches his movie idea. He tries to explain what he's trying to do, making a movie where nothing happens because, "nothing like that really happens in the world." At which point the instructor tells a mortified Charlie in front of 500 people that he doesn't want to waste his time with such a movie. In a spectacular monologue, McKee rants, "Nothing happens in the world? .... People find love, people lose it. For Christ's sake, a child watches her mother beaten to death on the steps of a church. Someone goes hungry. Somebody else betrays his best friend for a woman. If you can't find that stuff in life, then you, my friend, don't know crap about life." he also tells everyone that voiceovers are lazy writing. At the very instant he says it, the movie stops using voiceover narration (which it had hitherto relied heavily on).

Charlie tracks down McKee after the seminar and, over a drink, McKee tells him that a great movie only needs a great ending, no matter how messed up it is before that (which is poignant since we now know he's describing this movie, though he doesn't know it). He also cautions Charlie never to use deus ex machina (an improbable, unexpected occurrence that helps the heroes overcome their obstacles). His parting words are that Casablanca, the best screenplay ever written, was created by twins. Charlie needs to work with Donald.

From that point on, the movie becomes a delightfully Donald-esque thriller. It also manages to include every single thing Charlie swore he wouldn't put in his movie, including a deus ex machina (and a tiny bit more voiceover). I won't give away the ultimate ending, but it's a shocker that might leave you a little choked up... and a little hopeful about your own future.

Taken at face value, the movie goes from being unfathomably difficult to follow to consisting entirely of overbearingly formulaic action. However, it works not because of what's on screen, but because we understand that what's on screen is what the characters are writing WHILE they're on screen. It's amazing to see when and how Charlie decided to write what we've already seen, very fun to watch as we recognize all of the plot elements Charlie swore he didn't want to include, and an epiphany when we realize that Donald has started writing the ending that we’re watching.

In short, it's an exhilarating ride that any writer should appreciate!

Tuesday, January 8, 2008

"Who" and "whom" are NOT interchangeable!!

Ok, this is just a little diatribe on the use of "who" and "whom". I don't really mind when people just use "who" for everything. In fact, since English grammar relies partly on sentence structure to convey meaning, it doesn't really affect an audience's ability to understand. However, I can't stand when authors and speakers throw "whom" around incorrectly in a vain attempt to sound intelligent. I had someone doing just that earlier today, so I decided to explain when to use it.

To truly understand when to use "who" vs. "whom," you need to understand relative phrases. Relative phrases are really a type of subordinated sentence, whose subject noun phrase is converted to a relative pronoun. They're then used to modify the same noun phrase in a different sentence.

Here's a simple example. We start with two sentences. "The author wrote the book," and, "The author gave a speech." Notice that they share a noun phrase: "The author". We want to turn the first sentence into a relative phrase that modifies the noun phrase in the second. To do this, we replace the noun phrase with a relative pronoun, in this case "who", and move the relative pronoun to the front of the sentence if it's not already there (the relative pronoun is the signal that a relative phrase follows, so it must be first). So, the first sentence becomes "who wrote the book," and our combined sentence reads, "The author who wrote the book gave a speech."

Got it? Once you understand how relative phrases are created, figuring out whether to use "who" or "whom" becomes simple. Use "who" if the noun phrase you're replacing is the subject of the sentence and "whom" if it's the object. Let's modify our example slightly to illustrate. Let's make our first sentence, "The audience adored the author," and leave our second, "The author gave a speech." Now, when we change the first sentence into a relative phrase by replacing the noun phrase with a relative pronoun and moving it to the front of the sentence, it becomes, "Whom the audience adored," and our combined sentence becomes, "The author whom the audience adored gave a speech."

Make sense? That's all there is to it! Now, if only everyone would read this...

(Side note: The discussion on how relative phrases are created will resume when I discuss why I believe it's perfectly OK to end sentences with prepositions. Such suspense, I know!)

Monday, January 7, 2008

"Technical Writer" vs. "Documentation Specialist"

One of my recent managers adamantly opposed the job title "Technical Writer." Instead, he insisted we be called "Documentation Specialists." Now, I've always felt the latter term was cryptic and self-important sounding; I preferred to be a plain technical writer. However, after he explained his reasoning, I began to see that the term "Technical Writer" doesn't really encompass all that we do.

Think about it from a purely descriptive standpoint. When people who have no idea what we do see that term, what do they think? "Technical" connotates, well, complicated information for a highly-educated audience. "Writer" limits the scope of our contribution to simply putting words on paper. Is that the whole of what we do? I think not.

We translate technical content into language that other audiences can understand. We bridge the gap between engineers/programmers and the rest of the world. That translation requires more than just the right words, though. Everything about our documents (or websites or videos or... actually, the choice of the appropriate medium is another facet of our contribution) helps convey the information.

We interview and research; in fact, we have to be experts at dealing with sometimes difficult people to get the information we need. We must be highly proficient with any number of software programs. We're photographers and graphic artists. We're desktop publishers. We're designers. We choose the layout, the colors, the fonts, the organization, the style guide... right down to the size and weight of the paper and the type of binding used to hold it all together. Some of us are even responsible for choosing a print shop, reviewing proofs and pushing the purchase order through.

In short, we do so much more than simply write technical materials. "Documentation Specialist" is a start, but even that title doesn't convey a true sense of everything we have to offer. I'll continue to think about a more appropriate title and let you know if I come up with one. Do YOU have any ideas?

Help! I don't understand active or passive voice (or anything else you're talking about)!

Hey folks, I wanted to point out that this blog, while (hopefully) useful to the casual reader, is really intended for experienced writers. I don't want to alienate my intended audience by including too much detail about concepts that they should already be familiar with. (Note to observant readers: I plan to discuss my stance on ending sentences with prepositions soon!)

Of course, if you're not an experienced writer, don't leave yet! Just know that I won't be explaining every concept I discuss, so you might need to Google a few words or phrases.

Friday, January 4, 2008

Is active voice always the right answer?

I know several writers (usually ones who came into the profession from an engineering or scientific lab environment) who maintain that passive voice is the ONLY way to write technical documentation. "Personal" pronouns, they claim, have no place in impersonal technical documents.

Of course, those of us who went to school for technical writing probably had the opposite drilled into us. Active voice is good! Passive voice is evil! I actually had them personified as super heroes/villains in my mind at one point in my education. The reasoning was that active voice provided a clear "doer" and (less obviously) it removed liability from the technical writer by assigning tasks to specific people (while passive might not clearly state who should do what, which might result in an unsafe work environment depending on the task at hand). Oh, and active voice is a lot more engaging and easier to read, since the sentences are structured in the way English speakers are normally taught to process them (no mental back flips required!).

However, in the real world, while writers should strive for active voice whenever possible, passive voice definitely has its place. I've found two circumstances where I use it often: maintaining focus on a subject and describing errors.

Passive voice lets you put the object of the sentence at the forefront. So if you're writing about a computer disk, for example, "The user should then take the computer disk out of the disk drive" can become "The computer disk should then be taken out of the disk drive." While we have no "doer" in this sentence, we do maintain focus on the disk. (Yeah, it's a simplistic example, but off-the-cuff examples have never been my strong point. In this case, I'd probably just write "Take the computer disk out of the disk drive.")

Passive voice also lets you remove blame from your user when you describe error messages. Why bother? Well, users buy products and thus pay your salary. You want them to feel comfortable with the product, not skittish. Thus, any problem they have shouldn't be described like it's their fault (even if it is). "If you remove the disk while the program is installing, the computer will crash." Yeah, stupid! (That's the message you're delivering there.) Whereas "If the disk is removed while the program is running..." focuses on the action, not the person doing it.

Anyway, just some thoughts on active vs. passive voice. Discuss...