Write Technology

TextFlow Makes Document Collaboration Easy

cross-posted from bub.blicio.us

 I'm a social media consultant but really, in Cincinnati, that doesn't get me a lot of traction at the moment. So my bread and butter is instructional design and technical writing. It's not always the most exciting work, but it helps pay the bills. In the process of technical documentation, I may get two or three versions of the same document, edited by developers, SMEs, and overzealous copyeditors. I then have to incorporate all those changes into my master document. In the past, that's involved some hard copies, where I check things off as I integrate the changes.

It looks like that's all about to change. TextFlow by Nordic River made some news early last summer, but they've released their Adobe Air application in a new beta, and it looks pretty awesome. I haven't tried it out yet, but I'll be taking it for a test run in early January when I expect a documentation nightmare to appear on my desk. TextFlow allows you to drag different versions of a document into their app. It will merge them, highlighting the differences, and allow you to show the changes, hide them, and integrate them. From the perspective of a technical writer, this is a real timesaver. They have a fantastic (but non embeddable) demo video on their site, but here's a great video from C|Net's Josh Lowensohn demonstrating the product.

Embedding Linked Images in a Word Document

I googled the phrase in the title a lot the other day.

I had created printed documentation from a large Flare Help file. Everything exported perfectly. Then I moved the document to a different directory. When I opened it again, all my images were little red Xs. They were linked instead of embedded.

I wish Flare gave me an option before creating the printed documentation: embedded or linked images. I went through a lot of rigmarole before finally figuring out how to get the images embedded so I could share the document. I did not find much information on the web, which is why I'm writing this post. I hope it saves someone the headache I had.

A couple of tips:

• Before you try this, make a copy of your document in the same directory, just in case things go wrong.
• Perform this procedure before you format and resize all of your images.

Here's how to embed your images:

Generation who?

Tired of hearing the various generational terms thrown around? It does get old, and I admit to being terribly guilty of the offense. Everything from Generation X, Millenials, Digital Natives, Gen Y, they all make it into this blog.

A great Wikipedia entry on the Silent Generation (those born in the 1900s or 2000s) offers a fantastic chart on the generation name game, starting with the Puritan Generation in the 1500s and continuing through the New Silent Generation in the 2000s. It's worth a look.

(Via Boing Boing)

Technorati Tags: generation X, generation Y, generations, millenials, digital natives

Tufte on Presentations

Today I'll post Tufte's presentation tips. He provided tips not only on how to lead a successful presentation, but how to evaluate a presentation. I need to point out that Tufte feels that PowerPoint is the epitome of everything wrong with presentations today. Just read his article "PowerPoint is Evil" in the September 2003 issue of Wired.

Presentation Tips

• Use Word or a PDF instead of PPT.
• Provide a short hand-out on an 11 x 17 page, followed by a discussion. A high-resolution data dump on the handout  can lead to targeted questions in a short period of time.
• Provide a space for your attendees to write.
• Know your content. Quality, relevance, and integrity of content are important. When creating your presentation, get started by writing a 200-word summary to focus in on relevance and integrity.
• Practice, practice, practice. Rehearsal improves performance.

Tufte and Visual Presentation

Last fall, I attended a seminar taught by Edward Tufte, the master of visual communication. While expressing his disdain for PowerPoint, he imparted many tips, and I realized I never shared them on this blog. The wealth of knowledge I pulled from that seminar is too extensive to detail here, but a couple tips can be applied to presentations, graphics, print, web, and eLearning. His design principles are indifferent to gender, language and medium of delivery. Tufte approaches design from a scientific point of view.

Over the next day or two, I'll post his tips and suggestions as culled from my pages upon pages of notes from that day. We'll begin with the visual display of information.

User Input: My Little Dream

Technical Writing and Wikis

I think a lot of technical writers are sort of steeped in the past. Even if we're not personally refusing to move forward, a lot of our companies tend to think of training and documentation as that little group of people in the basement. Let's get the facts to them last and cut their budgets constantly. I experienced it as a cubicle and office dweller. As an independent contractor, many of my clients find me because they realize - at the last minute - they need some sort of documentation. My best clients allow me to document as the software is being developed, factoring the documentation into the life cycle of the product.  I'd like to take it one step further.

Currently, I might create a Help system. Despite prodding, most of my clients are still attached to basic CHM files. I'm currently using Flare to develop Help systems. Because Flare is XML based, it single sources my content. I create User Guides in Word 2007 (Beta) directly from the Help. Because Word 2007 is also XML based, the transition is seamless. Once the Help and User Guide are developed, my job is done until the client decides to issue an update to the software, usually a year later.

I don't want my job to necessarily end when the release date comes around. My little dream is to post my Help (or User Guide) topic by topic on a Wiki hosted in the same spot as the product knowledge base. Maybe the customer support reps for the software have access to the Wiki; maybe the consumers access it as well. Regardless of who accesses it, the minute someone does, it becomes a live document. Users post to the topic, mentioning what was forgotten or a tip or trick that they learned. When the time comes for the next generation of product and documentation, I can refer to the Wiki to learn what else really needs to be in my Help/User Guide and what extraneous information needs to be removed. 

User input into the documentation.
Learning, and understanding, how your documentation is used.

For underappreciated technical writers, what more could they ask for? 

Oh yeah, the budget to do it. Well guess what, there are a lot of open-source and free wikis out there that are either hosted or that you can host. (TiddlyWiki is a favorite of mine, partially because of the name, I admit.)

Wikis have amazing uses beyond just user documentation. I've attended conferences where the session discussions are continued for month by accessing wikis. My husband uses wikis extensively, as a live compository of knowledge in his workplace and as an interactive guide for a role-playing game.

Web 2.0. The technical writers are ready. We just need to bring our employers/clients along with us.

Technorati Tags: technical writing, wikis, Madcap Flare, documentation

Lacking in Flare

I've been trying to write this post for a week. I have mixed emotions about the whole thing. I'm uncomfortable with how I feel regarding Madcap Flare. Despite my earlier enthusiasm, I can't currently recommend that you run out and purchase this product. There's a caveat to this. I don't think you should run out and purchase RoboHelp either.

RoboHelp is in a state of limbo right now. We don't know what Adobe is going to do with the product. They may kill it completely. Alternatively, Adobe may resurrect RoboHelp so that it is better than ever.

If you must purchase a Help system, hold off until fall. At that point, perhaps we'll know more about RoboHelp's state. Fall, I believe, is also when Madcap will release Flare 2.0. While I can't encourage you to run out and purchase 1.1, I hope that 2.0 will offer significant improvements over the existing software.

UsersManualGuide.com

When I'm developing a new manual for software, or in particular, hardware that I know absolutely nothing about, I sometimes find it helpful to look at similar manuals. I like to see how other writers approached things and try to understand if their layout/approach/design/etc works for me, as a reader and user. Sometimes other manuals also explain things a lot better than my SMEs ever do. Before, I would always dig through various resources to find example manuals. That is now slightly easier. UsersManualGuide.com, despite the clunky and slightly redundant title, is a nice little repository of manuals of everything from Audio Mixers to Vacuum Cleaners. Enjoy!

Technorati Tags: user guides, user manuals, technical writing

Digital Glossary

With technology advancing as fast as it is, new words and slang are inevitable. Ten years ago, who'd have thought "iPod" would be as ubiquitous as "Kleenex"?
Lisa Belkin tackles the new word order in two articles for the New York Times: Overly Wired (4/9/06) and Coming to Terms with a Wired Age (4/23/06). (Free registration req'd for the New York Times or just visit BugMeNot.)
Some of the terms she encounters/comes up with include

Screensucking: "wasting time engaging with any screen — for instance, computer, video game, television,Blackberry." He goes on to use his new word in a sentence: "I was supposed to write that article, but instead I spent the whole afternoon screensucking." That concept hits particularly close to home.
Logonorrhea: a related condition that renders you unable to use certain online accounts because you can remember neither your screen name nor your password.
Bluetooth fairy: a person who walks around with the blinking glow of a Bluetooth headset permanently in one ear.
Cylences: The long gaps in phone conversation that occur when a person is reading e-mail or cybershopping at the same time.
Stripped: The opposite of wired, when your computer tells you that there are wireless networks all around, but not one is accessible without a password, or when your computer tells you it has a signal, but won't connect for reasons it refuses to share.

Technorati Tags: digital language, digital slang,language

Madcap Flare

About a month ago, I posted on my frustration with RoboHelp. After all, it's never a good sign when an entire development team disappears.

This development team re-materialized in the form of a new company called Madcap, with the flagship product of Flare. Madcap Flare could be the first serious challenger to the RoboHelp monopoly.

I downloaded the Sneak Peak and wasn't overly impressed. However, the sneak peek file is a pre-1.0 release and it is hobbled by its very sneak peekiness.

I had some questions regarding the maintenance, support, and so on and spoke with some members of the Sales Team. The Sales Team was very, well, sales team like. I got a hard sell. In the end, I ended up emailing with Mike Hamilton, VP of Product Mgmt. He answered my multiple questions patiently and over the course of a Saturday and Sunday. I simply can't express how impressed by am by this customer service.

Today I purchased Madcap Flare, although 1.0 is officially released tomorrow. I'll start developing with it in a week or two. From now on, unless a client specifically requests RoboHelp, I will most likely use Flare as my primary Help development tool. I suppose the future of Help, for me, is now.