Looking to learn MadCap Flare? If you’re a new Flare user, you’re probably feeling a bit intimidated. Features abound, and the learning curve is steep.

You can embark on several learning paths to Flare mastery:

• Try Flare’s excellent, comprehensive online help. The problem is, you may not understand certain concepts well enough to know where to start.
• Take a MadCap course. They offer a Basic-to-Intermediate class for beginners. They also offer Advanced CSS and Single Sourcing classes.
• Try the excellent topical guides (PDF) under Flare’s Help > Guides submenu. The guides provide a structured, linear learning approach.

All three options are great learning paths, but what if you want a comprehensive reference book?

Easy. Buy Five Steps to MadCap Flare by Lorraine Kupka and Joy Underhill. The authors are Technical Communication pros with over 40 years of combined experience between them. If you’re new to Flare, you can adopt their best practices from the start. If you’re an experienced Flare user, you’ll get a broad perspective that you can apply to existing projects.

Learning by Example

For readers who are new to topic-based authoring, Five Steps gives an excellent primer in the short chapter called Document Basics. The organization of this chapter—and all chapters, for that matter—exemplifies the practice of modular writing. The authors organize Information in easily digestible chunks with clear labeling. They also provide short reference sections such as Terms to Understand and include brief, easily scannable tables to help you sort out various options.

A Quick Tour provides a brief orientation to the Flare interface, emphasizing the conventions used in many of the side panes and settings windows. The chapter includes plenty of annotated screen captures to help orient you to the UI components.

Breaking your Stride

Don’t make assumptions about the notion of learning Flare in five steps. Kupka and Underhill have crafted each “step” as a category that subsumes a large chunk of knowledge. I’ll summarize the steps here and add some of my own comments.

Step 1: Get Started

This step gives pointers for planning your first Flare project, teaches you how to the perform common tasks, and introduces you to Flare templates.

Many Flare users plunge into creating a project without pre-determining the nature of its content and purpose. Planning your Flare project gives you guidelines in the form of questions. For example, do you already have source content or do you need to create it? Will you deliver both online and printed versions? How will your content be reviewed? The authors provide a useful roadmap in table form to help you make the right decisions.

If you’re used to creating templates in applications such as Word or FrameMaker, you’ll find Flare’s template model to be far more versatile and expansive. A Flare project can serve as a template, and each of its internal files can be templates, too. You can save most files outside of a project and reuse them in multiple projects. Since most of them are XML files, you can view them in a text editor. Flare 6 introduced the Template Manager, which makes saving and reusing templates much easier. In the section titled Working with Templates, the authors recommend best practices for using templates and explain how to use the Template Manager.

Step 2: Learn the XML Editor

Although the Flare authoring environment works like a word processor, it’s packed with features that are unique to the application. Step 2 walks you through nine core tasks for learning and customizing your environment. De-cluttering your workspace suggests that you close the panes on the right to increase your viewing space. (I also recommend saving customized workspaces for various tasks.) The Learn More section covers key visual indicators such as the structure, tag, and span bars.

Step 3: Develop Content

In this step you learn how to work with essential content elements. Here’s a partial list of covered topics:

• Working with lists provides thorough coverage of single- and multi-level lists, including how to rearrange, sort, re-number, and merge them.
• Working with tables explains basic tasks such as inserting, deleting, and moving rows and columns. Since Flare also uses specialized style sheets for tables, the authors continue the subject of tables in the formatting section. I second their recommendation that you create and store table formats in templates for reuse.
• Working with images explains how Flare manages changes to images. This section thoroughly covers resizing images and explains how resizing affects their quality.
• Formatting your content and Customizing styles both provide advice for controlling the appearance of your online and print content. You can supplement this information with one of my recommended books on CSS.

Step 4: Create Navigation Aids

The Help authoring community has many lively online discussions about navigational elements included in application help. For example, whether to include or exclude an index always seems to rouse passion.

In Step 4, the authors avoid editorializing about what to include or not include in your projects. They simply explain how to add and manage all of the available aids that Flare offers:

• Creating a Table of Contents provides thorough coverage of how to add one or multiple TOCs and how TOCs support online and print output.
• Creating links provides a useful table that describes all of the types of links that you can add to a Flare project. It explains how to add each type, including the Related Topics help control.
  Tip: If you’re using Flare 6, don’t forget about the Link Viewer, which enables you to trace link paths and dependencies.
• Adding cross-references explains how to add cross-references for your print output. Flare has great power and versatility for creating and managing cross-references. For example, contextual page number references can detect whether a referenced item is above or below the discussion point.
• Creating index entries explains how to add index keywords to your projects by adding markers to topics. (Like Word and FrameMaker, Flare uses embedded markers.) This section also covers how you can vary index output by adding conditional tags to markers.
  Another Tip: I’m a big fan of the Index Explorer (View > Index Explorer), and it’s greatly improved in Flare 6. Use this feature to monitor the state of your index during project development.

Step 5

Step 5 is split into two sub-steps, with 5A covering printed output and 5B covering online output. In both sections, you learn to set up project components and build the output.

Step 5A: Create Print Output
The good news about creating print output from Flare is that once you set it up, you can easily update and regenerate the content. The bad news is that setting up printed output is arduous. In fact, I’ve written six posts covering print setup.

Fortunately, Five Steps gives you a logical, well-planned strategy that includes preparation and decision-making. The authors divide the process into nine tasks. They recommend that you start with a simple print document so that you understand how to build the components, then graduate to a more complex document with multiple sections.

I’m a fan of this approach. I typically create (1) a simple print setup for sending individual or groups of topics to reviewers; and (2) a more complex print setup for double-sided, multi-sectioned documents.

Step 5B: Create Online Output
This sub-step follows a similar progression to Step 5A. The main difference is that it focuses on online components such as master pages and skins. It also includes a useful Testing and troubleshooting section.

Supplementing Your Learning

The five-step process summarized in this review gives you the core skills you need to master MadCap Flare. But the authors didn’t stop there. Appendices A through H offer useful, detailed supplementary information, including the following:

• Appendix A: Planning Worksheets includes the following worksheet examples for Flare projects:
  • Defining content sources
  • Defining project outputs (Example: WebHelp, WebHelp Mobile)
  • Determining how reviews will be handled (Example: MadCap X-Edit, MS Word)
  • Establishing project settings (Example: location, source control bindings)
  • Recording your target settings (Example: master page, medium, condition tags)

  These worksheets help you with planning and tracking. They also provide a concrete trail for another author who might serve as your backup or who might eventually inherit your project.

• Appendix B: Import Content explains how you can import MS Word, FrameMaker, or HTML files into Flare.
• Appendix C: XML Reference summarizes the XML Editor UI elements, including toolbars, cursors, and shortcuts.
• Appendix D: Context-Sensitive Help eloquently breaks down the process of mapping topics to UI elements.
• Appendix E: Troubleshoot offers tips such as fixing broken links and interpreting build errors.
• Appendix F: Single-Sourcing focuses on Flare features used in single-sourcing content, including condition tags, snippets, and variables.
• Appendix G: DITA Import and Export explains how to get DITA content into Flare and how to export it from Flare.
• Appendix H: The Next Step provides a roadmap for exploring additional Flare features that are not covered in the book.

Summary

In Five Steps to MadCap Flare, Lorraine Kupka and Joy Underhill have provided a clear, easy-to-follow guide to mastering Flare. They start with tool-agnostic, sound advice on planning an information development project. In the Flare development context, they emphasize projects and templates as the key building blocks.

I also appreciate how the authors set best practice examples for all information developers to follow. They write in plain, conversational language. They use consistent conventions that facilitate ease in finding information. And they’re damn good teachers.

Buy the book now.

Back to top

Intimidated or befuddled by the process of getting FrameMaker content into Flare? I have written an article on the subject for MadNewz, MadCap Software’s online newsletter. The article expands on my previous post about FrameMaker importing.

Thanks to everyone who has tweeted and retweeted about the article! I will be presenting a follow-up webinar for MadCap on October 6th, 2010, from 11am – Noon PST.

Related Links

• MadNewz: Ten Tips for Importing FrameMaker Content into Flare
• This blog: Preparing FrameMaker Files for Importing into MadCap Flare

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.

Related 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

During the last couple of weeks, my partner and I moved our home and office to Alexandria, VA. We are still living out of boxes and wondering where to find some of our stuff. At least we’re here and our stuff is here, wherever in the condo it might be.

To reward ourselves for surviving the move, we are spending next week with family on the North Carolina coast. I plan to do a lot of reading and relaxing. And I expect to be berated by my family for my choice of reading material. They don’t consider what I read to be conducive to relaxation. I simply like to read non-fiction and technical books. So as I select books to take along, I have considered subjects ranging from sociology to usable design to taxonomy development.

Even though we donated boxes of books to a local library before moving, the remaining number of books were a major burden. We have many voluminous titles. Yet, as I browse for books that I can conceivably finish while on vacation, I notice that many of the more recent books—especially technical titles—are significantly smaller and more focused on specific aspects of a subject.

For example, note the page counts for the following books. Each count includes the index:

• Donna Spencer’s Card Sorting: 9 x 6 inches and only 162 pages
• Rockley, Manning, and Cooper’s DITA 101: 9 x 6 and only 133 pages
• Richard Sheffield’s Web Content Strategist’s Bible: 8.5 x 5.5 inches and only 209 pages. This book is hardly a “bible” in the sense of the huge, all-inclusive, door-stop-sized tomes from Wiley. Even so, it’s rich with information on content strategy, while many of those other “bibles” have a lot of fluff.

I refer to these smaller, more focused titles as “juicy little books.” I appreciate their size and the quality of the information. All three are available as downloads (PDF), and DITA 101 is available by print on demand (POD) on Lulu.com.

Another juicy little book is Scriptorium’s classic, Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content. Authors Sarah O’Keefe and Alan Pringle have updated the book to include information on Web 2.0 and DITA. The recently updated third edition is available as a PDF download from the Scriptorium site or as a POD paperback from various sites. You can also read a great review of the book by Keith Soltys.

I haven’t yet become a Kindle user, but I can envision a day when I use a Kindle or similar device and start recovering some living space. In the meantime, I’ll reclaim more space with my juicy little books.

Back to top

My life as a new condo owner is currently filled with moving details and arrangements: cable installation, lock replacement, and minor upgrades and fixes resulting from our home inspection. One detail that caught me off guard and required some research was the selection, purchase, and installation of a new garbage disposal.

Let’s face it: garbage disposals are not one of those things that an average person thinks about. Unless your unit is on the wane—or as in our case, dead—you’re unlikely to wake up one morning and say “I think I’ll shop for a new garbage disposal today.” You probably won’t find yourself habitually gravitating toward the disposal display in Sears, either.

But for the past few days, I have been preoccupied with garbage disposals. My browser has been choked with an array of tabs, each displaying search results and home improvement sites. I have been reading specs, making comparisons, and learning the jargon. I learned to pay attention to specific attributes: continuous feed, sound insulation, grind chamber capacity… induction motor vs. permanent magnet motor…

One model even comes with a “self-service wrenchette … for easy clearing of jams.” My word processor doesn’t recognize wrenchette. I suppose that’s a sort of faux French word for “little wrench.”

Another model makes your life easier because

two grind stages let you quickly grind difficult food waste you wouldn’t put in a standard disposer, like celery and potato peels.

I hate when food waste is “difficult.”

Learning Through Research

Like most people, I start with the Web when I’m trying to tackle a new knowledge domain. Through research, I was able to narrow down my choice of product and find out where I could purchase it.

Conducting Web research reminded me that I cannot search the Web without informally evaluating the usability of sites. None of the sites that I found explained the meaning of the disposal product specs. The meaning of some terms was obvious, and I could infer the meaning of other terms such as grind capacity. But terms such as sink baffle kind of… well… baffled me. I went on a wild word chase: baffle as noun = “something that balks, checks, or deflects.”

OK, I realize that these sites simply want to sell products, but a good customer is an educated customer, right? A little embedded help can’t hurt.

Learning from Experts

My research also reminded me of the discovery process that we technical communicators constantly employ whenever we start a new project. I thought of all the domain knowledge that I have acquired over the years.

At one point I oversaw a large-scale training project at the World Bank. The Bank was rolling out an ERP system, and I was responsible for developing training for the procurement module. I had never worked in procurement, and I spent many hours attending meetings—even on Saturday mornings—with procurement experts.

At the National Cancer Institute, I took on medical terminology thesaurus management. I dove deeply into papers and books on Description Logics and Knowledge Representation. I worked closely with information scientists. I developed a fascination with Tim Berners-Lee’s idea of a truly semantic Web.

Over the years, I have become immersed in many other domains, including telecom engineering, clinical care, accounting, mortgage products, law office management, and manufacturing plant flow simulation. The key to acquiring domain knowledge is to work closely with subject matter experts, or SMEs (pronounced “smeez”).

In one of my most successful projects at the United States Mint, my SME was a seasoned accounting professional. Our task was to produce a training course for the customized accounting module of another ERP system. We worked under a seemingly impossible deadline, using a collaborative strategy where my SME developed raw content for conceptual detail and exercises, and I provided additional writing, editing, organization, and overall design. We met the deadline, and our course was well received.

Projects where software developers were the appointed SMEs did not always proceed as smoothly. In most cases, software developers are in the same position as information developers. Like us, they have to acquire the domain knowledge and expertise to truly understand the needs of the users.

Users are the real SMEs. They use the products and follow the processes every day. Spend time with them. Observe them. Listen to them. Learn from them.

What’s Your Story?

What on-the-job knowledge have you acquired over the years? Which domains were especially challenging? I hope that you will share your stories.

Back to top