After yet another hiatus from regular blogging, I recently made a resolution to rekindle this site during the US Labor Day weekend. So here I am.

2010 has been an interesting year for technology. This summer I’ve shared many links to tech news and stories (and sometimes made irreverent social comments) on my Twitter page. I’m going to expand on that practice in this space. I could save this subject for an end-of-year retrospective, but I would like to share information about some of the devices and software that have made lasting impressions (good and bad) on me so far.

Impressionable devices

Here are some hardware devices that I’ve begun to use or been exposed to this year.

Verizon Droid

I finally became a smartphone user last winter. (You can stop laughing now.) I was a late adopter because I was conditioned by trying to get the attention of my Blackberry-addicted friends and colleagues. When contract renewal time rolled around, I decided to take the plunge.

Since I’m a long-time Verizon customer and a regular user of Google Apps, I chose the original Droid phone. Of course the Droid 2 was released after six contract months had passed, but I’m quite happy with the original. The sync-up with my Gmail accounts and contacts is seamless, and a recent OS upgrade greatly improved the integration with MS Exchange email. With its Google Maps integration, the performance of the built-in GPS has been far more effective than our dedicated GPS device. And while I originally thought the inclusion of a hardware keyboard was a bonus, I now prefer the screen version.

XLink Communication Hub

Last year my partner and I replaced our aging home handsets. We bought a new Panasonic DECT 6.0 base unit and four handsets that are conveniently placed around the condo. When we decided to ditch our landline this year, we lamented wasting money on the handset upgrade. Then a friend told us about the XLink Communication Hub.

The XLink is a Bluetooth-enabled device that pairs with up to three Bluetooth-enabled cell phones. It recognizes your paired phone as soon as you walk in the door. It also pairs up with your 6.0-enabled handsets, so you can answer and place calls through your cell phone using the regular handsets. We bought docking stations for the Droids, so we never have to worry about losing them. Placing and receiving calls at home is business as usual.

iPad and tablet devices

I mostly use an iMac with virtualized Windows and plan to eventually buy a MacBook Pro. I also still use a two-year-old Dell XPS laptop. When the iPad was released, I wasn’t interested. Then my nephew brought one to a family gathering, and I began considering the practicality and usefulness of a tablet device.

A conversation among my inner demons goes like this:
“Nah, stick with a laptop.”
“Tablet. Tablet is better.”
“Get both!”

I’m keenly watching Apple and its competitors. With my new affinity for the Droid, I’ll certainly consider an Android-powered tablet.

Impressionable software

In April 2010, I joined a User Experience team as Managing Editor of a government website. The focus of my responsibilities has shifted quite a bit, and so has my use of software. I do most of my copywriting in an HTML editor, and I rely heavily on MS Office 2007 for project documentation. I also use a number of handy open-source utilities (which I’ll cover in a later post), but I’ve been more impressed by the following 2010 software releases than anything else I’ve used.

Windows 7

I’ve established that I’m primarily a Mac user these days, but I started using Windows 7 when I took on my current post. I had been using Windows Vista SP1 on my Dell XPS laptop, and despite all of its press, I had no major problems. Since Windows 7 is essentially a refined version of Vista, I adapted easily. I’m impressed with its improvements and performance. It’s what Vista was intended to be and should have been all along.

My laptop is nearly two years old, and I recently replaced Vista with Windows 7. The laptop is having a second life. It actually seems to run better and faster. I’ve also installed Win 7 on the Mac in a Parallels Virtual Machine, and that’s working well, too.

Yes, Mac friends, you heard right. I LIKE Windows 7. I still prefer using OS X, but I’ve become a fan of the newest version of Windows.

MadCap Flare 6

As evident from my last few posts, I spent the first quarter of the year developing MadCap Flare templates for the National Cancer Institute’s Center for Biomedical Informatics and Information Technology (NCI CBIIT). I developed a project template and other internal templates such as page layouts and targets. I find Flare 6 to be the most robust version yet, with many great new features and UI refinements.

Flare users, watch for the following topics:

• In this space: A review of Five Steps to MadCap Flare, my favorite resource for learning Flare.
• On the MadCap site: An upcoming article about FrameMaker-to-Flare imports in MadNewz, MadCap’s online space for articles and related webinars.

I also want to mention that a DC-area colleague, Laura Johnson, has launched a great resource site for all things Flare. Laura has been a Flare expert since version 1.0, and she now shares that expertise on her blog, A Flare for Help. Be sure to visit. I’ve added a link to my Related Sites list in the right column of this site.

Back to top

In my last post, I discussed ways that you can build lists of related links in your MadCap Flare projects. I expressed a preference for concept links.

If you share my enthusiasm for concept links and are importing FrameMaker content into Flare, you may want to pre-configure your source FrameMaker files to include Passthrough markers with special strings. When you import the marked FrameMaker content into Flare, the Passthrough markers convert to concept markers in the equivalent Flare topics.

You can then insert a concept link help control in each topic that contains the same marker and build a dynamic list of related topics. I described this process in the following post:

MadCap Flare Tip: Helping Users Find Related Information

When preparing your FrameMaker files to include Passthrough markers, follow these steps:

1. Add a custom Passthrough marker to each FrameMaker file. If you’re not sure how to set up markers in FrameMaker files, read this post:

   Preparing FrameMaker Files for Importing into MadCap Flare

2. Insert a Passthrough marker in the heading of each topic that is related to the same concept.
3. Add the following string to the Passthrough marker definition:

   <MadCap:concept term=”term” />

4. Substitute “term” with your concept term, keeping the quotes (“”). Make sure that “MadCap” has an uppercase M and uppercase C.

To ensure that the markers convert properly, enable the following Flare import settings. If you’re using an import file in your project, you’ll find these settings on the Options tab:

• Enable ‘Passthrough’ Markers = Checked
• Passthrough Marker Format = XML

Back to top

When creating online help or user assistance, a common practice is to include a related topics link at the end of a given topic. The link usually appears as a clickable button labeled Related Topics or See Also. When a user clicks the button, a pop-up list of related topics appears, as shown below. Each topic is a clickable link.

In MadCap Flare, you can create this type of link using help controls. Flare offers three types of help control, and my favorite is the Concept Link. This control builds a dynamic list of topics that are associated by a concept. You first have to insert concept markers into the topics to create a concept association among them. This type of linking relationship is similar to A-links in other help tools.

Inserting a concept marker

Before you insert a Concept Link help control into a topic, you need to add a concept marker. To insert a concept marker, follow these steps:

1. Open the topic.
2. Open the Concept Window: View > Concept Window.
3. Do either of the following:
   • Add a new concept term by typing it in the entry field at the top; or
   • Select a previously added concept term from the list in the lower half of the window. For each existing term, you can click the plus sign (+) to the left and view a list of topics that are associated with that term. You can also drag terms into the open topic to create new markers.

I usually place both concept and index markers at the very beginning of a topic, before the topic title.

Creating a pop-up concept link

Now that you have created concept associations among topics by adding markers, add a concept link to the end of each of those topics. This procedure creates the pop-up link that users see in your help output.

To create the pop-up concept link at the end of a topic, follow these steps:

1. Open a topic that contains a concept marker.
2. Select the following menu command:
   Insert > Help Control > Concept Link (A-link).
3. Select a term on the right.
4. Click the directional button in the middle of the window to copy the term to the left side of the window.
5. Click OK.

Other types of help control

Flare offers two other types of help control. You’ll find both of them using this menu command: Insert > Help Control > [Type of Control].

Related Topics control

This control enables you to manually build a list of related topics by selecting files. The control appears as a button with the label Related Topics.

For more information, see these help topics:

• Inserting Related Topics Links into Topics
• Editing Related Topics Links

Keyword Link control

This control builds a dynamic list of topics that are associated by an index keyword. You first have to insert index markers into the topics to create a keyword association among them. The default label for the control is Search Index.

For more information, see these help topics:

• Inserting Keyword Links into Topics
• Editing Keyword Links

Another Option: Relationship Tables

When MadCap introduced DITA publishing capability in Flare 5, they cleverly integrated DITA relationship tables as yet another way to introduce related topic links. You can use this powerful feature in non-DITA projects. For more information, see About Relationship Tables.

Questions?

Help controls and relationship tables enable you to give users a simple way to find related information. They also enable users to learn by association. I encourage you to use these features when using MadCap flare to develop user assistance.

If you have questions or comments about these techniques, please add a comment or contact me.

Back to top

I haven’t written a post about MadCap Flare for a while, and the release of Flare 6 deserves special attention. With this version, Flare remains miles ahead of its competition.

When a new version of Flare is released, I usually install the new version and keep the last version installed, too. After testing the rock-solid Flare 6 beta during the past few months, I was easily convinced that I could fully upgrade on the GA release date. Flare 5 is no longer on my laptop.

I recently created Flare templates for the National Cancer Institute’s Center for Biomedical Informatics and Information Technology (NCI CBIIT). The Information Development team currently uses Adobe FrameMaker and Quadralay ePublisher. Lately I have been busy preparing Adobe FrameMaker files for import into Flare, running import routines with various settings, and testing the results.

I recommend the following process for preparing your FrameMaker files before importing their content into MadCap Flare. I will provide additional advice and tips in upcoming posts.

1. Back up your FrameMaker files.

Read this aloud: Create a backup copy of your FrameMaker files. You’ll need to alter them for an optimal import, so work with a copy—not with the original.

2. Remove formatting overrides.

Regardless of the tool you’re using to develop and publish information, you should use styles (called tags in FrameMaker). Styles automate the formatting process and ensure consistency.

Examine your FrameMaker files and make sure that they’re free of inline formatting created with the Formatting toolbar. In FrameMaker parlance, this type of formatting is called an override. In Microsoft Word, it’s called direct formatting.

I will provide advice on style mapping between Frame and Flare in an upcoming post. I have already included some advice on cleaning up your styles in a previous post. For more information, read the first of my six articles on Flare print publishing.

3. Add indentation to TOC sublevels.

A typical table of contents uses indentation to represent a hierarchy. In a Flare TOC, book icons are flush with the left margin, and topics and subtopics are indented.

Before importing a FrameMaker book, make sure that the FrameMaker TOC sublevels are indented. Flare relies on this indentation to properly create an equivalent TOC.

You can do this for FrameMaker TOC styles (levels 2 and below) by setting a property on the Basic tab of the Paragraph Designer:

1. Select the following menu command: Format > Paragraphs > Designer.
2. In the Paragraph Tag list, select the tag you want to change (for example, Heading2TOC).
3. Click the Basic tab.
4. Set the First property to a specific value. For example, a Level 2 TOC heading might be set at .25 inches, and Level 3 might be set at .5 inches.
5. Click Apply.

4. Predetermine the file names in your Flare project.

FrameMaker is a linear writing tool. Flare is a topic-based writing tool. When writers who are used to authoring in Frame first switch to Flare, they sometimes become disoriented in Flare’s authoring environment. Although Flare generally does a good job of naming topic files, the names might not always be what you expect.

To ensure that you can find your content in Flare, add a custom Filename marker to each of your FrameMaker files. You can then add this marker to FrameMaker chapter names and topic headings. During import, Flare creates a file for each chapter introduction and topic using the name that you pre-assigned.

Example:

• Let’s say that a chapter is called Browsing Terminologies. You insert a Filename marker in the chapter name and define the marker as intro_browsing_terminologies. (I typically prefix chapter introductions with intro. They also serve as section introductions in WebHelp.)
• Now let’s say that the first topic in the chapter is About the Terminology Browser. You insert a Filename marker in the topic heading and define the marker as about_terminology_browser.

During import, Flare creates one file for the chapter and a second file for the topic:

• intro_browsing_terminologies.htm
• about_terminology_browser.htm

You can set the permitted length of file names in the Flare import settings.

Adding a custom Filename marker to a FrameMaker file

To add the custom Filename marker to a file, follow these steps:

1. Select the following menu command: Special > Marker. The Marker window opens.
2. Click the Marker Type drop-down list.
3. Click Edit in the bottom of the list. The Edit Custom Marker Type window opens.
4. In the new window, follow these steps:
   1. Type Filename.
   2. Click Add.
   3. Click Done.

Adding the new marker to a FrameMaker chapter
or topic heading

To add the new marker to a chapter or topic heading, follow these steps:

1. Click anywhere on a chapter or topic heading.
2. Select the following menu command: Special > Marker.
3. In the Marker Type list, select Filename.
4. In the Marker Text box, type the file name that you want Flare to use for the current topic. Remember, you don’t need to append the .htm extension.
5. Click New Marker.

I highly recommend this method. It’s very helpful when you need to find content in your new Flare project.

5. Specify Adobe Distiller settings
for optimal image quality.

Since Flare uses Adobe Distiller to convert images, you can use Distiller to improve image quality in the imported FrameMaker content. To accomplish this, you need to specify custom Distiller settings and save them as a custom .joboptions file.

To specify your Distiller settings, follow these steps:

1. Open Adobe Distiller.
2. Click Settings > Edit Adobe PDF Settings.
3. Select the Images folder on the left.
4. For each Downsample setting, select Off.
5. For each Image Quality setting, select Maximum.
6. Click Save As.
7. Name your custom settings file. For example, mine is flareimport.joboptions.
8. Click Save.
9. Click OK to close the settings window.
10. Close Distiller.

Distiller uses the last saved file, so it will use your custom file.

Questions?

The basic steps that I have covered in this post will help you prepare your FrameMaker files for importing into MadCap Flare. I didn’t discuss the time-consuming task of mapping FrameMaker styles to Flare equivalents. I will cover that subject in an upcoming post.

As always, I welcome your questions and comments.

Back to top

My friend and fellow writer Kai Weber raises an interesting question in a post called “Does structured writing stifle creativity?” The migration to XML architectures has a lot of people asking similar questions.

I have long pondered a more broad version of the question: Is technical writing really a creative profession?

The inevitable cocktail party conversation

At cocktail parties and other social events, I often meet people who aspire to make a living in fiction writing, poetry writing, or graphic design. When they learn that I make a living in technical communication, they ask how they might become a technical writer. They’re attracted to the idea that they can at least make a living writing while they develop their creative talents.

I understand the idea and the logic very well. I come from a fine arts background. I have a degree in music education and performed in nightclubs and concert halls for years. I own copyrights for nine songs. I have dabbled in poetry and have a collection of unpublished poems in my filing cabinet. Unfortunately, I never had the drive to succeed in music or fiction/poetry writing. Passion, yes; drive, no.

I landed my first corporate job to support my musical endeavors. The education part of my degree paved my path to technical communication. I had been trained in educational psychology and understood how adults learn. I could write lesson plans. So when I entered the job market in the late 80s, I started developing courses and training mainframe users. With the increasing emphasis on technology over the years, I added technical writing to my skill set. I have straddled the instructional design and technical writing worlds ever since. Both disciplines appeal to my bizarre mix of left- and right-brained thinking. I’m creative but very methodical.

So how do I answer the cocktail party question? I respond with a question: What technical discipline do you want to specialize in? Technical communication comprises many disciplines: Science writers write about science. Medical writers write about medicine. Technology writers write about hardware, software, information security, and many other aspects.

Typical answers: “Well, I use a lot of software,” or “My degree is in biology.” From there, I try and make suggestions for resources, leading to an exchange of business cards. I also point out that technical writing is business writing and requires a lot of team interaction. It’s not a solitary profession where you are left alone to mine your creative imagination.

True creativity in technical communication

To wind up the cocktail conversation, I stress what I think is the number one requirement for succeeding in technical communication: creative problem solving. Writing is just one aspect of your work. You have the opportunity to apply your research and investigative skills to helping others.

Whether you are developing a knowledge base or a training video, your goal is to provide user assistance. By helping users solve their problems, you enable them to complete tasks and accomplish goals. I realize that this isn’t a new or original assertion, but it bears repeating.

For more information about how your work profoundly influences users’ daily lives, see the following post: Paving the Road to a User Utopia.