Thursday, August 7, 2008
MadCap Flare, the help author's dream tool
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
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.
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
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
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
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!!
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)!
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?
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...