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.