To All You Out-of-Towners: Welcome to Vancouver!

Google Map: Yes, it is no coincidence that this year's DocTrain West takes place at one of downtown Vancouver's most beautiful waterfront locations!

It's fairly late in the evening as I write this. I'm all prepared to get to bed early so I can awaken early enough to arrive at the Pinnacle by 9am. It just dawned on me that many out-of-town visitors coming to this year's DocTrain West may not have been to Vancouver before. After a long day of workshops and networking at the conference, you might feel less than obliged to traverse very far out into the streets of downtown Vancouver; however, I urge you not to miss the opportunities that await you. When you're able to get an hour or so break in between workshops, go for a seaside stroll and take in the breathtaking views at Coal Harbour. It's really only a few minutes NW from the hotel's doorsteps.

Even better, after attending all your workshops on any of the conference dates (pick a sunny day), find a buddy, rent a bike that fits you comfortably, and leisurely ride the entire seawall (approx 10-12km) at Stanley Park. There are plenty of bike rental shops near the corner of West Georgia and Denman - about a 15-20 minute walk from the hotel. Yes, it sounds touristy, but I can almost guarantee that you'll have one of the most relaxing and eye-popping experiences on this side of urban North America.

And as you may have already heard, Vancouver is very much a foodie town. Downtown Vancouver provides a wonderful sampling of what Canadian Westcoast cuisine has to offer, along with a myriad of ethnic eateries enough to make your head spin. To help you decide, I highly recommend the local Dinehere.ca restaurant review site.

That's all for now - see you all tommorow!

DocTrain West 2008 is Almost One Month Away!

Brace yourselves tech-comm geeks and wannabes! DocTrain West, perhaps THE largest conference of its kind in the North American west coast, will be held in Vancouver BC this year. With over 35 industry professionals scheduled to appear in almost 50 workshops, you'll be sure to know that there's something for everyone.

ATTENTION!
Register before April 15 and save $100 on a full access pass!

If your boss isn't already aware of the conference's benefits to you and your company, and you want to attend without sneaking out of work and paying out of your own pocket - then you've got to sell, sell, and sell. Make a case for it, and make it clear to your manager what you'll be getting out of it. There are really only three basic steps you need to know:

1. Do your research - start with the links above.
2. Identify the workshops that you think are most applicable to your role, department, or team objectives and include them in your written request/proposal. Don't forget to mention concrete benefits and tangibles for a more convincing case.
   
3. Submit to your boss and be prepared to discuss your interest in attending the conference.
   

Hope to see you there!

Getting to Know Framemaker: Conditional Text

Imagine being able to produce multiple flavours of one single print document through the simple use of tags. We’re not talking about XML quite yet – but a tool in FrameMaker (FM) that can help you churn out different renditions of the same document by having select text appear or not appear.

Conditional Text

Using a software manual as an example, you may want to render certain chunks of text associated with a particular version of the software as conditional. You can then associate those chunks with a condition tag name of your choice, and then choose to hide or show the condition tag as required. Conditional text allows you to avoid the chore of cutting and pasting text and all the things we hate about maintaining multiple versions of a document. This would be a huge benefit to any newbie who is just starting print documentation work and a great way to start employing niftier methodology without opening the XML door just yet.

To illustrate how this would work with the simplest example: 1) I’d grab the latest Version 1.1 user manual (.doc), and then export its contents into a .fm file. 2) I would add/change new content where appropriate in the .fm file for the upcoming 1.2 release, and then tag newly added text with the condition tag “1.2”. If a sales rep needed version 1.1 of the manual, I would simply hide the “8.2” condition tag in FM and generate a PDF accordingly. If a technical analyst needs an 8.2 version of the manual, I would select to show all condition tags, generate a PDF, and so on. The result would also save lots of memory space in your repository!

Unfortunately, conditional text is not a built-in feature available for Word 2003 (not sure about 2007 though). If you're still examining the switch to FM and have yet to try the month-long free demo, you can download a copy at the Adobe site here. To learn more about conditional text in FM 8, just look up ‘conditional text’ in FM’s LiveDoc search.

Even better, with DocTrain West coming up, you don't have to learn FM alone! Bring your laptop with the FM 8 demo installed and ready to go, and let Matt Sullivan of GRAFIX Training and Consulting teach you how to really tap into the power of FM and its sibling applications available in Adobe's Technical Communication Suite. His pre-conference workshop takes place this coming May 6 at Pinnacle Ballroom 3 of the Vancouver Marriot Pinnacle.

Getting to Know Framemaker: Books

My department is finally giving serious consideration to join the Framemaker (FM) club thanks in part to the open mindedness of my relatively new boss, who, like me, has recognized that it's time to divorce ourselves from the ubiquitous MS Word 2003. Before we jump board, I've been given the task to get a better understanding of FM, and how it would benefit our documentation and organization as a whole. Expect a few more posts about FM in the next little while :)

One of the things that distinguishes FM from Word is that it has the capacity to pump out long documents at relative ease. A feature that helps make this possible is the Book feature. There’s tons of useful information on this in the Framemaker User Guide (p.455), so I don’t want to bore you with excessive details.

Currently, a typical software manual is written in one single Word .doc file. This can be a pain to navigate around when editing and adding content, especially when each manual has the potential to go over 100 pages. What the Book feature offers to do, is break the manual into individual chapters and collect each chapter into one book (.book file). So essentially, each chapter, including the table of contents, becomes a separate document (.fm file). Pages can be numbered continuously from one fm file to the next and cross-references can be updated all at once. Even better, each .fm file can have its own numbering system (e.g. the TOC can have roman numerals).

What this all means is that if we were to use the book method, we’d do less scrolling, avoid the mistake of altering parts of the manual we didn’t intend to, and have a better picture of how the manual is structured. And that's a good thing.

Personas

Trish is 35 years old. She's been working at the company for 10 years now as an office administrator. In the morning, after she gets her coffee, she would spend 15 minutes checking her e-mail inbox in MS Outlook. She would then open up her Outlook calendar to see if she has any meetings to attend for the day. Most of her daily work tasks are done in MS Word. She's quite confident in her Word abilities, but would consider herself as the last person to ask for help when it comes to troubleshooting Excel - what she considers as the least understandable piece of computer software ever made...

I've been taking a creative copy writing class after work, and found that good copy writing shares at least one common trait with good technical writing. That is, we all write, or should write, to a persona. Words don't exist or form in a vacuum; there is no all-encompassing method to explain how a jet engine works. Nor would we ask the actor to wear a chicken suit in a TV ad with the hope to sell more life insurance policies. Before a technical communicator sits down to design a manual or help system, there's always one thing worth asking - how are you fulfilling the needs of your users of the product or service your company is selling? Your writing could have lots of information, but if delivered incorrectly, your efforts will have turned out in vain.

If your organization doesn't have a lot of resources to allow for expensive surveys, or have customers come in to the office to complete usability tests - creating a persona may just be the ticket for you. The fact is, personas have already been in use in the design process for many of the products you use. Big software companies that focus on user-interface design, have long employed personas as part of the development process. There are many benefits. Here's an example of a few:

• They ensure that designers adopt the customer's mental model rather than their own, while avoiding second guessing of customer needs.
• They put a human face to customer data, and therefore allow a clearer visualization of how your customer is using the product.
• More than one persona can be used to represent the needs of a multitude of different users of your product.

When creating a persona, there are lots of information you can gather. What is this person's job experience level? What does their typical work day consist of? What do they like about their job? What do they hate? What are their career ambitions? What is their attitude towards technology? What is their name. What do they look like? The more convinced you are that this fictional character exists, the more effective the persona will be for your documentation and training design.

Joe Sokohl, a user experience specialist with over 15 years of experience, will be speaking at an hour-long session at DocTrain West this year. As part of the agenda for Changing the Rules of the Game for the Benefit of the User, he will be discussing how he's successfully employed personas to develop relevant and on-target training for his clients.

How to write in Plain English

A guide titled "How to write in plain English" was introduced to me in a technical writing class a couple years ago. I highly recommend you save a copy for your own personal reference. Here is a quick summary drawn directly from the guide:

• Stop and think before you start writing. Make a note of the points you want to make in a logical order
• Prefer short words. Long words will not impress your customers or help your writing style.
• Use everyday English whenever possible. Avoid jargon and legalistic words, and explain any technical terms you have to use.
• Keep your sentence length down to an average of 15 to 20 words. Try to stick to one main idea in a sentence.
• Use active verbs as much as possible. Say 'we will do it' rather than 'it will be done by us'.
• Be concise.
• Imagine you are talking to your reader. Write sincerely, personally, in a style that is suitable and with the right tone of voice.

Stick by these general principals and you're well on your way to writing good ol' Plain Jane English!

Plain Jane English

Concise writing in what I call 'Plain Jane English' has always been something that's been neglected by noobie technical communicators. I admit that I'm no less guilty and am continuously honing my Plain Jane English skills at work. When you enter the technical communication world with your bachelor of arts or science, gone are the days of your feeble attempts to emulate the work of your admired professors - long winded and pretentious research papers, where big words and complex sentences reign supreme. If you come from a creative writing background, say goodbye to smilies, metaphors, and 'foreshadowing'.

It's the harsh truth - your readers aren't going to snuggle up in bed with a cup of warm cocoa and the latest copy of your fax owner's manual (*boohoo*). They are, however, going to be using it to learn how to do something very specific - like say, to change their printer's ink cartridge. Assuming your general readership consists of the lay variety, the more Plain Jane English you use, the easier and more pleasant their experience. In sum, Plain Jane English is:

• Straightforward and easy to understand.
• The dominant writing style in technical communication.
• Consists of non-technical words (whenever possible) and simple compound sentences.
• Used for the sake of clarity and accuracy of information.

There are many benefits in using Plain Jane English and believe me, the transition from writing complexly to simply can be difficult. Luckily, at this year's DocTrain West conference, those who seek to tighten their writing and better understand what Plain Jane English can do for them can treat themselves to a pre-Conference workshop hosted by Berry Braster. The workshop, called Simplified Technical English: How Standardization of Content Will Reduce Costs and Facilitate Quality Assurance, will take place on May 6, between 1-5pm at the Vancouver Marriot Pinnacle. Barry will also touch upon the topic of documentation standardization, and how simplified English lowers localization and reusability costs.