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

Recently I have read a lot of books about the state of web content. I have been contributing web content for many years, and I have long advocated that well-structured, clear content is vital to a successful user experience. So I am fascinated to see the sudden surge of interest in content strategy.

It’s about time.

Web sites have long been products of shiny bauble design: Make it pretty and they will come. A site lures you in, but you quickly discover that you cannot find what you’re looking for. Either there’s not enough information, or there’s too much information, but it’s so poorly structured and organized that you give up.

Information architects (IAs) who focus on design over content have long fueled this problem. The best IAs realize the value of the user experience, where design and content are fully integrated. They focus on both aspects. But sometimes the scope and breadth of site requirements place too much responsibility on them. A partnership becomes necessary.

Enter the content strategist.

In this post, I discuss two books that are shaping the body of resources on content strategy. This is not an in-depth review of either book. Both are only around 200 pages long, and I don’t want to give away all of the authors’ secrets. After reading this post, I hope that you will read these excellent resources.

Mired in a swamp of content

For years companies examined their organizational content with the goal of deploying some expensive mega-monster to house it. They hired content management consultants, many of whom were employees of content management system (CMS) vendors. Those consultants analyzed and modeled samples of the content. This practice led to a consistent, similar recommendation:

“Buy our tool.”

Many companies followed the advice, believing that a new CMS was a panacea that would pull them out of the muck. Instead, they ended up with a costly and not-very-effective “solution.” The complexity of the tool overshadowed the organization and effectiveness of the content.

To make matters worse, content often took a back seat to overall site design. Wireframes for site pages focused on shiny baubles and navigation. Other than navbar and menu labels, many areas were simply filled with lorem ipsum. Filler words made sense for creating a design sketch, but they also fostered a mental model that made content the illegitimate stepchild of site design.

We now seem to be waking up to the reality that effective information architecture goes hand in hand with effective content strategy. I’m ecstatic. I have always viewed content as integral to web design.

So who is codifying this new knowledge?

Rescued by the team of Sheffield and Halvorson

Two recent books offer slightly different but useful perspectives on content strategy as a profession:

• The Web Content Strategist’s Bible by Richard Sheffield
• Content Strategy for the Web by Kristina Halvorson

Both books are a great introduction for budding content strategists who (1) want to know if they have the qualifications for the job, and (2) want a big-picture perspective of what content strategists do.

The Web Content Strategist’s Bible
by Richard Sheffield

Richard Sheffield’s book was the first of the two to be published. His book describes his rise from a sequestered, contract technical writer to a content strategist at IBM. He provides a comprehensive overview of how the content strategist fits in with the rest of the web site development team. He gives examples of content strategy job descriptions and encourages readers not to be discouraged by all of the listed requirements. He says that anyone with “decent” writing and editing skills, a basic understanding of the web, and project management abilities is qualified for the job.

Sheffield defines content strategy as

a repeatable system that defines the entire editorial process for a website development project, from very early tasks such as analyzing and classifying readers to the very last tasks, such as planning for the ongoing content maintenance after the content launches.

The author points out that content strategist is an evolving role, subject to misunderstanding. (Who’s surprised?) Project managers often set “arbitrary time frames” based on a “lack of understanding of editorial processes.” They also do not understand the role of the content strategist.

Sound familiar?

In fact, according to the author, CS professionals are in a position similar to where IAs were in the mid to late nineties. In a section titled Web Content Strategist vs. Information Architect, he asks whether IAs should handle content responsibilities or whether both roles should be required. This question sparks lively debate on the web and in numerous pubs.

Sheffield devotes seven chapters to phases of the content life cycle:

• Discovery: Embark on a fact-finding mission about the organization and its content.
• Analysis: Present your findings and make initial recommendations.
• Design: Work with graphic designers, content creators, and others to create tools and processes (such as templates, a style guide, and a content matrix) that support the remaining project phases.
• Build: Track content development, editing, and approval.
• Maintenance: Establish who will maintain the content, how it will be tracked, and how it will be deployed.
• Translation: Ensure that content meets the requirements for translation, and where necessary, for localization.
• Search Engine Optimization (SEO): Establish keywords, links, and other findability factors.

Chapter 10, What You Need to Know About Web Content Management Systems ensures that you have a basic understanding of how content management systems work. It also arms you with the vocabulary necessary to keep up with—and contribute to—team discussions about the CMS.

Content Strategy for the Web
by Kristina Halvorson

The author of Content Strategy for the Web is the founder and president of Brain Traffic, “a nationally renowned agency specializing in content strategy and writing for the web” (from the back of the book cover). Brain Traffic employees have authored many excellent online articles and resources. See the end of this post for links.

Halvorson defines the purpose of her book as “an introduction to the emerging practice of content strategy.” She disqualifies the book as the be-all, end-all bible of the practice. As she says, “A lot about content strategy is still being figured out.”

Although she acknowledges that content can include many media, Halvorson focuses on text as content because

• “Text is everywhere.” We see mostly text on the web.
• “Text is different.” Once we publish it, it needs continued “care and feeding.”
• And my favorite: “Text is messy as hell.” It’s constantly changing and has many owners.

Before covering the content life cycle, Halvorson provides a section called Learn. The three chapters in this section (Solution, Problem, and Discipline) serve as a content strategy primer. I especially recommend those three chapters for managers, stakeholders, and anyone who is skeptical about adopting a content strategy.

For example, if your company isn’t ready or willing to make the plunge, maybe you can convince key staff to at least read Chapter 1, Solution. Halvorson introduces it as the chapter for those who “only have the time and attention to read one chapter.” Whoever reads it gets enough information to at least start thinking about content strategy and considering a short course of action.

Halvorson presents her ideas and recommendations in the manner of a workshop facilitator. She identifies problems by asking probing questions. She tackles them with solid, often enumerated answers. Like Sheffield, she walks you through her version of the content life cycle, framed in a slightly different way:

• Audit: Understand what you have and get a sense of the scope.
• Analysis: Determine how your content will serve your users and how it will improve your competitive position.
• Strategy: Recommend “how to create, deliver, and govern web content.”
• Workflow: Establish a process to move your content through all necessary channels, including delivery.
• Writing: Elevate your web writers above the level of worker bees by making sure that they are recognized as key team members. Involve them in ongoing content maintenance.
• Delivery: Consider your delivery channels. Do you need a CMS? Do you need social media?
• Measurement: Use web analytics to measure the effectiveness of your content.
• Maintenance: Care for your content using a “well-designed process that continues over time.”
• Paradigm: Write a strong, convincing business case that proves the worth of your content strategy.

The fact that the author once held positions as both a web writer and a copywriter is no surprise, but her perspective as a business owner and consultant informs Content Strategy for the Web. She strongly emphasizes content that “[s]upports a key business objective” and “[s]upports a user (or customer) in completing a task.” She recommends not necessarily imitating your competitors but being aware of what their content conveys.

As part of the the analysis phase, Halvorson recommends that you determine what messages your company hopes to convey to its customers through its web site. You later recommend how those messages can help to develop and shape user-centered content.

So which book is better?

It depends. The two books complement each other. Aspiring or working content strategists will want to read both for the varied but useful perspectives. In fact, in her own Workflow chapter, Halvorson refers to Sheffield’s guidelines for designing content workflow. She refers to his book as “an excellent primer for anyone who is trying to get their organization’s web content under control.”

If you need concrete examples of many deliverables that are required for a content strategy project, start with The Web Content Strategist’s Bible. It provides an example of how you might structure a content audit worksheet. It also includes suggestions for how to construct other project and strategy documents.

If you want your manager or any company stakeholders to read one word on content strategy, I recommend Content Strategy for the Web. While the book certainly speaks to the content strategist, it is also geared to a wider business audience.

Relevant links

• Richard Sheffield’s site
• Brain Traffic site

Back to top

Interested in learning more about the Darwin Information Typing Architecture (DITA)? I recommend that all information developers at least break the surface. Regardless of whether you plan to adopt DITA, you can benefit from studying it. You can even borrow from its lean, efficient writing model.

I have been a fan of modular, “chunked” writing since I took an Information Mapping (IM) course years ago. Although I see value in using IM, I prefer DITA’s open, simplified, XML-based model. I appreciate its emphasis on standardization and content reuse. I like the flexibility for using specialized information types. Although none of my clients have adopted DITA, I study it because I have a driven fascination with information architecture and structure.

Toe in the water or swan dive?

Most of the available information about DITA is on the web, but at least three DITA-related books have been released (as far as I know). Each of the following titles is a great resource for neophytes who find the formal specification a bit intimidating but who would like to learn more about—and possibly even experiment with—DITA.

DITA 101: Fundamentals of DITA for Authors and Managers

This 2009 release is written by Ann Rockley, Steve Manning, and Charles Cooper, three esteemed members of the Rockley Group. The book provides a straightforward introduction to DITA without becoming mired in technical details. It provides an overview of the DITA architecture, explains the benefits, and gives advice for planning a DITA implementation. It includes just enough “Advanced Stuff” (the name of the final section) to orient you toward the language of DITA. Best of all, it’s written in the same crystal clear style as Managing Enterprise Content, also a Rockley publication and one of the best books on content management.

DITA 101 is a “toe in the water” book. If you need to make a business case for DITA or compose an elevator speech, this book is your best resource.

Practical DITA

Author Julio J. Vazquez places more emphasis on the planning and execution of DITA projects. In Practical DITA, he encourages authors to start with a visual map of their information set and refer to the map throughout the information development process. He emphasizes the importance of audience and task analysis.

Of the three books discussed here, Practical DITA offers the most detailed writing advice. Vazquez introduces the basic DITA information types and explains the role of each. For example, he lists questions that a concept topic should answer. He recommends that cognitive tasks be written as concepts. He emphasizes the importance of writing “generically” and limiting related links to external content.

Practical DITA also exposes readers to the basic mechanics of DITA. The author covers such specifics as semantic naming and common semantic elements, syntax diagrams and how to create them, filtering and flagging, and linking relationships.

If you are committed to DITA adoption or simply want to develop a test project, I recommend Practical DITA as prerequisite reading. This is your “starting to dog paddle” book.

Introduction to DITA:
A User Guide to the Darwin Information Typing Architecture

Introduced in 2006 by Comtech, this book is a comprehensive tutorial. After a brief overview of the DITA architecture and the core information types, it plunges headlong into hands-on exercises. You open your XML editor and build topic examples. You work with DITA maps. You learn techniques for content reuse and specialization. You install the DITA Open Toolkit and build output.

Introduction to DITA is your “starting to swim” book. This book is the choice for information developers who want experiential guidance in DITA content creation. You not only learn by doing, but you also become acquainted with many DITA elements. Although I recommend this book for practice, I give equal weight to Practical DITA for its sound advice.

Ready to take the plunge?

Good luck on your DITA journey! I have provided links for online DITA resources and for each of the three books discussed here. If you have additional resources or comments to share, please write.

Explore some online resources

• Learn more about DITA from the perspective of its creator, IBM
• Read the OASIS DITA Specification
• Visit the online community for the DITA standard
• Read the Wikipedia entry for DITA

Buy a book

• DITA 101: Fundamentals of DITA for Authors and Managers
• Practical DITA
• Introduction to DITA: A User Guide to the Darwin Information Typing Architecture

Back to top