Demystify Captivate’s Vague “Error” Message

If you’re new to Adobe Captivate, as I am, you’ve probably been stymied by the mysterious message, “Error”, that appears when you try to convert Captivate’s native .SWF file to .AVI for use on YouTube.

That’s it. “Error”. Adobe provides nothing else. No clickable links. No Help. Not even a hint. Just the word, error, in the center of your screen. I’ll spare you the speech on usable errors and warnings. Preaching to the choir, no doubt.

I don’t know about you, but I despise when I am beaten by a mere machine.  I played around with various settings, and spent countless hours performing Google searches.

I will not be beaten!

Eventually, I discovered the reason for this obnoxious message:  resolution. Yep. That’s the big secret. Captivate requires resolution set at an even number, so if you’ve accidentally rescaled your project to an odd number… “Error.”

To change resolution

1. Click Project, Rescale.
2. Change the width and height so that both values are even
3. Save settings

Repeat the conversion. It should now work without “Error” messages.

If anyone has Captivate tips/tricks, I’d love to hear from you.

It’s an honor to have been nominated

The organization to which I belong awards top performers in various categories every quarter with what’s called a Core Values Award.  Since its inception, the awards are historically granted to developers whose code resolved a software bug, or whose 24 x 7 performance implementing a hardware upgrade kept the entire network alive.

You know… super-hero type things.

You can imagine my astonishment to learn I had been nominated for such an award. Because tech writing is a field that struggles for respect (see earlier rants blog entries to this point), I was beyond thrilled to have been nominated, particularly given the outstanding talent in the company I keep.

For my work on the D2D project, I’ve been producing videos, blog entries, and HTML topics instead of the usual PDF guides. The project is in beta and the feedback is trending positive.  I’m excited about this work – I’ve been blogging about it incessantly – and I talk about it constantly.

It was that excitement that earned the nomination. Alas, I did not win the thousand-dollar-bonus prize but it truly was an honor to have been nominated.

Cloudy skies ahead for tech writers

It’s been almost a year since I started hearing about The Cloud at work, a nebulous (grin) metaphor for the internet – or so I’d thought.  Many months and countless hours of research later, my interpretation of the term, and its impact on technical communication, have evolved.

Here’s my elevator pitch definition:

Doing business a few years ago forced you to invest small fortunes implementing IT technology that obsolesced before it was paid for. That’s like buying your own plane when all you really needed was an airline ticket. Today, the internet lets you buy IT technology as its needed – pay for only what you use, as long as you use it. This commoditized wealth of computing power, software, and services is The Cloud. In the cloud, brand names don’t matter –  Intel Inside, Solutions for a Small Planet, or Where do you want to go today  – what matters is the technology is there, it’s ready when you are and it goes away when you’re done with it. The Cloud helps your business concentrate on business.

Of course, my definition has a distinct end-user focus. Ynema Mangum, in her guest post on Just Write Click, dives deeper into types of clouds, but it seems to me that an end-user focus is appropriate if we are to determine how the cloud impacts technical writing.

My first observation is this  -  if users’ computing power, software, and services live in the cloud, shouldn’t also their instructions for using that technology? In fact, as the technology becomes commoditized, so must the customer information that supports it.  We’re already seeing content generation shift from a manufacturer- to a community-driven endeavor with the explosion in popularity of wikis, blogs, and forums.  Along with community-generated content, I think making that content portable and accessible will become a primary goal of writing for the cloud. Imagine being able to edit a procedure from any device, collaborate with subject matter experts live in a webcast and instantly distribute your up-to-the-minute content to your entire user base. Sarah O’Keefe agrees, saying small (or maybe, no?) desktop application footprints will mean technical writers can access content from anywhere.

I’m also learning that procedures must change so that content development can exist as a separate and agile effort divorced from the product development cycle.  We’ll need to learn and exploit more web technology (screen casts, videos, social networks, Help, RSS feeds, etc.) to make this possible.  And we’ll need to do all this while balancing it with the principles of good technical writing – concise, clear direction.

As soon as I figure out how to do all that, I’ll let you know. In the meantime, here are some links that helped.

http://www.idratherbewriting.com/2009/12/23/i-find-that-youre-very-central-and-visible-responding-to-reader-questions/

http://www.scriptorium.com/blog/tag/cloud-computing

http://antitechwriter.com/antitechwriter-blog/60-let-the-cloud-help-the-crowd.html?template=js_jamba

http://www.internationalstudentjournal.com/vnews/display.v/ART/2009/06/15/4a368d075f001

http://www.masternewmedia.org/cloud-computing-key-trends-and-highlights-from-george-siemens-media-literacy/

http://ltc.umanitoba.ca/blog/2008/12/the-year-of-the-cloud/

Managing feedback deja vu

Early in my technical writing career, I remember wishing for expert feedback to validate my work, tell me I was on the right track, that I’d written the right information.  Back then, the best we could hope for was a good copy edit to eradicate typos because access to qualified subject matter experts was at a premium.

Today, I am fortunate to be part of a team that adheres to a proven process, which prescribes a series of reviews during development. A peer review ensures I follow departmental standards. A technical review ensures I’ve written the right information, correct and complete. A quality assurance team tests the information I’ve written against a working version of the product and identifies problems and gaps. From each review cycle, I receive draft upon draft of suggested revisions.

Talk about too much information…

It’s great when somebody identifies an error. But what happens when what’s identified isn’t black or white but one of a few dozen shades of gray?

Obviously, I don’t know it’s a gray area at first. I simply make the revision.

And then, change it back.  And, change it once more.

I was astonished to learn that people disagree over what’s ‘correct’ in technical information.  I’ve also learned the limits of my memory. While I certainly remember changing the same bit of text three and four times over, I discovered I had no capacity for remembering who told me to change it.

Frustration mounted. I was a hamster on a wheel, running furiously and getting nowhere.

In desperation, I looked for ways to log and track who revised each content block. I think of it as meta-content. I used to embed hidden text, but learned it wasn’t hidden from the translation team. Today, I use a simple Word document. I start one at the beginning of a project, a pristine version of the doc before revisions.  With every review, I revise the source document as I normally would, adding an annotation to the Word document that detailed what I changed, who requested the change, and when I changed it. Sure, it’s extra work. But the peace of mind it gives me when I can recognize a requested change’s second appearance is worth every minute.  When that happens, I have Requestor One and Requestor Two battle it out and get back to me when they’ve chosen a winner.

There was one procedure in a software release that went back and forth like this for months.

Despite the extra time it takes to maintain, my Word tracker has saved me countless hours in unnecessary research whenever discrepancies occur.

How do you manage multiple changes?

Done… and feeling pretty darn proud of that

A few posts back, I blogged about needing help with my Help project. Of the psychological variety. What a pounding headache that project gave me. Here are some of the lessons I’ve learned.

Outline, outline, outline!

The time you spend organizing a help system is arguably the most important part of the project and should not be performed at the end, as I did.  I’d already written the manuals in the doc set and turning my attention to the Help forced me to shift gears from a task-based focus to a software focus.  I had to remind myself repeatedly not to get lost in the GUI screens.  Users could do thirty or forty procedures from one screen. Holy crow, where do I start? Context Sensitive  Help means uses can arrive at a particular help topic ‘out of context’.  Since my job is to provide that context, the importance of being organized was a point not driven home with such significance until then. I wish I’d done this sort of software-against-task analysis before I’d started the other documents in the set because what resulted from this effort was a better, crisper, more focused information set.

I began with the very first screen users view upon launching the software and compiled a list of activities – NOT procedures  – they can do, as well as a list they may want to do.  That list became the outline. I had to create several Help-only topics, even though I use a single-source authoring tool.  If I hadn’t already written the manuals, I might have been able to do a more effective job at single-sourcing. So, from Screen One, users could perform three main activities. Those three main activities became chapters in the Help contents.  By grouping related procedures, I was able to distill a master list of just several over-arching activities and build from there.

Which brings me to my second lesson.

Link, link, link!

One rut I out of which I’m trying desperately to claw is writing for sequential reading. The internet makes page turning a thing of the past. Information Elements, chunking, single sourcing – all these methodologies emphasize the need to develop content that can stand on its own.  If you want to perform a task, here’s a task chunk. You want more information? Here’s a concept chunk.  As I assembled the Help system, I noticed I’d failed to connect all these related chunks in any manner other than sequential because I’d already written ‘books.’  I went through the entry point topics, linked them to corresponding concept, task, and related information topics, as well as to the table of contents.

When I published the project and it failed, I thought I was doomed. Two days later, after painstakingly reassembling the master file one topic at a time, testing it… lather, rinse, repeat… I finally found the problem. I’d directed my publishing tool to omit a topic from the master table of contents, but left its child topics still set for inclusion. That one little checkbox took two days to find and disable.

So, lesson three is test as you go and then, test again.

When I, at long last, had ensured every link worked, every topic published, and every entry point into the system was not a dead end, I happily delivered the system to my development team, so that they can link topics to the Help buttons.

Project management decided to postpone the effort until the next release.

Final lesson – mental health professionals must be on speed dial.

Writing Content for Kindle-like Devices

I received an Amazon Kindle for Christmas and so far, I’m loving it, though I anticipate getting into a tiff with my husband over how much money I’ll be charging in books to our credit card.  The device is elegant, its controls are easy to use, and the screen is crisp, even in sun. Because it’s slim and lightweight, I can curl up into my favorite reading nook and forget I’m using an electronic device.  I keep it in my pocketbook so whenever I hear about the great book you just read, I can instantly buy it and download it. I don’t need to be tethered to a computer, such as when syncing my iPod.

Okay, I’ll spare you from any further gushing about my new toy, and get to my point. eReaders like Kindle provide a fantastic way to deliver technical information. Think about it:

• Environmentally friendly – no more trees must forfeit their lives to print out binders of instruction that sadly sit on shelves, only to be replaced with the next software release.  (I have three FrameMaker Guides on my shelf.)  Kindle lets us remove obsolete content.
• Portable – as small as a paperback and only slightly heavier than a BlackBerry, Kindle may not fit in a pocket, but can be easily transported.  Consider industries such as aircraft maintenance.  Instead of lugging about a heavy, out-of-date manual to the tarmac, technicians could just download the latest FAA directive on fixing the problem at hand to a Kindle.
• Electronic – It may feel and read like a book, but Kindle documents can still feature hyper-links to additional topics of interest within a document, or to an external website. No book can do that. The library it stores is backed up to Amazon, so even if the device fails, you won’t lose the content you’ve already collected.
• Scalable – Orientation can be switched so you can view a detailed schematic in landscape, when necessary. You can adjust text size, too.

My only complaint is that it offers no brightness or contrast controls and a backlight would be great for reading before going to sleep.

If no one reads the manual, that’s NOT okay

While catching up on my email, I just read Tom Johnson’s latest post, “If no one reads the manual, that’s okay” and have to respectfully disagree.

Tom, you make excellent points – I am aware that most users will call support before they’ll crack the spine on a shrink-wrapped user guide, but it’s still not okay. It’s not okay because we are still stuck with the tools and environments and processes that compel us to write and deliver those guides. Why are we not listening to our users?

I agree – users despise manuals.  This was a bitter lesson for me. I love to read. I love books. I love printed matter in all its forms. I do not understand people who don’t like reading. My husband is such a creature. With his help, I’ve come to – well, not understand it. ( I never will understand.) I’ve come to accept it. Different strokes for different folks, I suppose.  As my husband explains it, he has better things to do with his time than to research a problem or an error that designers should have solved before they released the product.  That usually sparks half a smile from me, because I’m also a student of “good enough” quality.  I understand the reality of producing a product on schedule and on budget. Some things just cannot be fixed by release date and so, are tossed into the documentation as a known issue or perhaps a task with a strange procedure.

So, if we know they’re not reading the documentation in the first place, why are we putting information there?

Instead of shaking our heads sadly that our work rarely gets read, shouldn’t we be researching how people really do learn a product’s use?  If most people hate to read, would they watch a video? Would they chat with other users in a public forum? Would they attend webinars? That old adage about the definition of insanity pops into my mind… Why, if “64% of men and 24% of women don’t read the manual before calling support”, are we still delivering them?  Why, if as “Ron Jeffries writes, ‘Your customer hates big manuals. He has shelves and boxes full of them just like you do.’(Manuals in Extreme Programming)”, are we still delivering them? Why, if as “Sheila Fahey of Cherryleaf explains, ‘When things go wrong and it matters to the user, they will seek assistance. They will look for the easiest way to get to the information they need to do the task. If this is the manual, then they will use it.’ (If no-one reads the manual, then why bother?)”, are we not making it easier to get the information they need to do the task?

I recently found a line of t-shirts emblazoned with the old RTFM slogan. After grinning and – yes – shaking my head sadly at the profundity – I am forced to acknowledge that when something becomes so true a t-shirt can explain it, it’s time to change.

We can’t afford to indulge the fantasy any longer – manuals are out of style. This should be a wake-up call. If users won’t read, how will YOU get them the information they need to use your product?

As I learn…

While working on our beta project, one thing I’ve learned is the importance of allocating enough time to manage issues. Tasks that should be minor often take the most time… I haven’t quite figured out why yet, but suspect that darn Murphy and his Law are behind it.

In the past two weeks, I’ve juggled all manner of problems including a broken RSS feed (I broke it by mistakenly deleting the category used to pull the feed), a server crash, and conflicting priorities on projects. I don’t have access to the software I have to document on one project and on another, those teeny minor problems are turning out to require huge chunks of time to manage.

Here’s an example… on my beta project, I’ve been recording videos for YouTube that last no more than 2 or 3 minutes. These videos are software demonstrations, which means I am recording a task in real time, using the subject software. Sounds easy, right?

And it should be.

But I seriously underestimated the time needed for post-production. Things like adding text callouts or audio narration take hours to do properly, even for a 2 minute video.  End result is that I have lost entire days just working on one task.

Then, there are software issues. We use AuthorIT for our documentation. I am not sure why, but the recent upgrade from 4.x to 5.x has been a nightmare for us. This stable and reliable product is now anything but. Topics won’t save, publishing books now frequently prompts Out of Memory errors even on machines where RAM is maxed out. Not Responding errors are also popular.  Another tool I use, Adobe Captivate, has a quirky “Error” message. That’s it. Just the word “Error.” It took me the better part of two days to discover the cause of the “Error” error was a screen resolution set to an odd number before converting to . AVI format.

As we beta test the product, improvements will require that I reshoot all video demonstrations. This time, I am ready for the various challenges software quirks and that Murphy guy are planning to throw at me.

So much to learn…

If you’ve been reading about my efforts to ‘think outside the book’, you already know my team has been involved in a new documentation project – software instructions provided via YouTube videos, Google Groups, and website. Beta starts soon and I’m nervous.  I think we did a great job with the whole customer experience but there’s still so much to learn and we’re learning those ropes while clinging to them.

How will we manage changes? It’s not just pressing the delete key and retyping new text anymore. Now, it’s recapturing screens, recording new narration, updating web pages and changing the code. 

Managing the Google Group is also a new concept. We’ve set up this group to encourage new users to exchange tips, solve problems and get help, but we’ll have to moderate it somehow. 

There’s a lot to learn, a lot for us to master and then fine-tune.

One thing’s certain… I’m having fun again.

If you’re using video demonstrations in your documentation projects, I’d love to hear from you.

YouTube Needs to Get with the Program

In my efforts to think outside the book, I’ve been working on a project that, for the first time, will deliver more than just the PDF user manual. We’ll be delivering HTML topics that include links to video instructions posted on YouTube.

As we prepare for beta, the interface is changing, user tasks are changing and the technical instruction is changing. The only that can’t change is YouTube.  The videos I’ve already posted cannot be refreshed or replaced with modified content. My only course is to delete the old and post a new.

Sound crazy?

We’re not alone. A quick forage through the YouTube forums shows dozens and dozens of similar pleas, but no word on whether YouTube plans to address this shortcoming.

So, to my laundry list of things that change, I must now remember to embed new links to the new videos whenever I delete an out-dated one.

Tell me how you’re using YouTube in your documentation projects.