Best-practice strategies for your documentation projects
585.383.1992

Rapidly prototyping a MadCap Flare project (Part 1)

Rapidly prototyping a MadCap Flare project (Part 1)

Getting from a glint in your (or your company’s or client’s) eye to a finished MadCap Flare project—especially in the absence of legacy or other source content—can take a lot of planning and effort. And when time is money, getting the Flare project set up as quickly as possible is an important business goal.

In this article, I describe one of my two favorite techniques for rapidly prototyping a from-scratch Flare project. That technique is mind-mapping.

I developed this prototyping technique for Flare 8, but it applies equally well to Flare 9 (with one exception—for the better, explained later).

The usual suspects

MadCap Flare offers many ways to begin a new project:

  • By importing legacy source content (e.g., from Word, FrameMaker, RoboHelp).
  • By importing from legacy output (e.g., from a .chm file).
  • By importing from DITA.
  • By copying a Flare project and then modifying it.
  • By using a Flare project template (e.g., the MadCap-provided “Web Print Mobile,” “Book,” or “Knowledge Base” template or a custom template that you or someone else has already invented).

What these methods have in common is that content already exists—some in full, other less so.

What if you’re starting from scratch?

But what if you’re starting with, well, nothing…

Empty pages

 

 

 

 

 

 

…and you need to get to a ready-for-development Flare project—one with a full set of topics, properly named and arranged in a neat Content Explorer, and with a TOC already populated with properly-named items that are neatly ordered? Maybe the topics are largely empty, but the structure of the Flare project is totally in place.

Prototype Flare project

If you need to get there fast, you probably don’t want to start with Flare’s “Empty” template. That will just give you a single, empty topic and a TOC with a lone TOC item to that single topic. You’ll need to add topics one-by-one and build the TOC item-by-item. Obviously, that will take time, no matter how fast a keyboarder you are.

So how can you get from nothing to a Flare project—quickly?

Don’t start with Flare—at all

When faced with creating a Flare project from scratch, I actually set Flare aside. In my opinion, it’s a development tool, not a design tool.

Instead, I use another tool to plan out the content I expect to create and maintain with Flare. I think of this as “prototyping” the Flare project.

Some authors may start in Microsoft Word or maybe Excel. My two favorite tools are mind-mapping software (covered in this article) and Microsoft OneNote (which I’ll cover in another article).

The general workflow is this:

  1. Create “topics” in the prototyping tool and, if possible, seed them with content.
  2. Export the “topics” to a Word document.
  3. Import the Word document into Flare.
  4. Continue with content development in Flare.

Design with a mind-mapping tool

A mind-map is a visual presentation of ideas in a structured arrangement that reveals the relationship among the ideas.

The particular software that I use for mind-mapping is MindJet MindManager, but any mind-mapping software that lets you do the following will work:

  • Quickly create and arrange (and rearrange) map nodes.
  • Add notes for each map node, not only as plain text but also as lists, tables, images—even links to URLs and links from one map node to another.
  • Output the map to a Word document in which map nodes become headings (with the correct heading styles applied automatically) and the nodes’ notes become content beneath the headings.
  • Output the map to a PDF, for review purposes.

General example of a mind-map

My mind-mapping software runs on Windows, but I could just as easily create a mind-map with software running on Linux, Unix, Mac OS, or even iOS or Android, as long as those apps meet my requirements. There are also cloud-based mind-mapping applications, some free or quite inexpensive.

Step 1: Map out “topics”

Below is a mind-map I created for my MadWorld 2013 demonstration on prototyping Flare projects. It’s the initial mind-map that I invented when prototyping an actual Flare project for one of my clients.

Preliminary mind-map of an eventual Flare project

The central node identified the name of the Flare project, while each of its sub-nodes would be the first-level topics, that is, those topics that would be associated with “books” on the TOC.

“AT” is an abbreviation for “Arbor Terrace,” the subject matter of the project to be prototyped. Actually, the “AT” project would be a sub-project merged into a much larger Flare project called the “Garden Archives.” Eventually there would be close to 70 of these sub-projects, so it was really important to invent a repeatable, timesaving workflow. Furthermore, if the bulk of the prototyping work could be done outside of Flare, I could enlist assistants who didn’t have access to—or even know—Flare.

I continued to expand the map by adding more “topic” sub-nodes beneath the major “topics.” At this point, with exception of the central node, the wording of the nodes and sub-nodes reflected the human-readable headings that my client and I planned to use in the topics.

Mind-map with more topic nodes added

After mapping out all of the “topics,” I sent the map as a PDF to my client for her review. She had some wording suggestions and even added a few more topics, which I incorporated into the mind-map.

Now the real power of prototyping could begin.

Step 2: Define the filenames of topics

In my practice as a topic-based author, I follow many guidelines when naming topic files, of which the most important is this: The filename of a topic must identify its type and, to a certain extent, its content.

I don’t want to go into too much detail about the filenaming conventions that my client and I devised. The important thing to note is that the filenames in the eventual Flare project would not match the human-readable headings. For example, the topic whose heading would read “Arbor Terrace, Balcony” would not have a filename of Arbor Terrace Balcony.htm but instead exh_drw_balcony_LA_GD_P-1-10_cor_et_al.htm. The “exh_” prefix would identify the topic’s type, in this case, “exhibit”; the “drw_” prefix would identify the topic as being about a drawing; and the word “balcony” would identify the subject of the drawing.

At this point, I used the mind-map to accomplish several things simultaneously, always keeping in mind that I would eventually pull this material into Flare:

  • Copied the human-readable heading of a node to that node’s notes.
  • Framed the human-readable heading in the notes within what I referred to as “pseudo tags” (e.g., [h2] instead of <h2>). (Downstream in Flare, I’d be replacing those pseudo tags with real tags.)
  • Edited the node itself to read as a filename, although without the .htm extension.

Nodes renamed as expected filenames, with the original node names retained in the notes

Step 3: Add some “seed” content

Where I could, I next added content to nodes’ notes, framing that content with other pseudo tags for styles that I planned to have in the Flare project’s cascading style sheet. I even added images, links, and pseudo index markers.

In short, I was “seeding” the topics with placeholder (and in some cases, actual) content.

More content added to the notes of mind-map nodes

Step 4: Export the map to Word

It was time to export the map to a Word document.

The mind-mapping software would create a Word document whose filename matched the central map node (and, when the Word doc was imported into Flare, that would become the name of the .flprj file).

The other map nodes and sub-nodes would become Headings 1 and Headings 2, and their notes would become content beneath those headings.

Word document created from the mind-map

I checked the resultant Word file, making small tweaks here and there where I realized that something was amiss, perhaps a missing “/” character in a closing “pseudo tag.”

All in all, I spent very little time in Word. Word was merely the bridge between the design tool and the development tool.

Step 5: Import the Word document to Flare

Finally, it was time to fire up Flare!

I set about creating a new project by importing the Word document. In the Import Microsoft Word Wizard, I made the following selections:

  • Turned off linking to the source document, as I’d not need it again.
  • Broke topics at Headings 1 and 2.
  • Configured Flare not to shorten the filenames too short, as I did not want Flare messing with my carefully designed filenames.
  • Turned off the Avoid Empty Topics option, just in case there were any nodes with no notes, as I definitely wanted those topics.
  • Did not create new styles, as I wanted complete control over the project’s style sheet.
  • Mapped the Word heading styles to h1 and h2 tags in Flare.
In Flare 9, there’s a new import option called Automatically set topic title, which is selected by default. Had it been available when I was inventing this workflow, I would have turned it off. (You’ll see why shortly.) I like to think that MadCap added that option just for me! I had submitted a feature request for that very option during the invention of the prototyping technique.

Presto, here’s what Flare did with the imported Word document. Wow!

There was still more to do, but at least I got files with the exact filenames that I wanted. I also got a TOC with topics in the correct order, although not yet in their finished human-readable form and without any nesting.

Initial Flare project after the import of the Word document

Step 6: Organize the Content Explorer

The next step was a quick reordering of the Content Explorer according to the major topic types my client and I had devised.

It was important to make these moves within Flare so that Flare would update the links from the topics to the TOC.

Reorganized topics in the Content Explorer

Step 7: Clean up the code

Now was the time for some power work to clean up the code of the topics.

Let’s examine one topic’s code. (See the numbered arrows in the following image.)

  1. A <title> tag.
  2. A link to a style sheet.
  3. A heading based on the topic’s filename.
  4. Paragraphs containing content, such as the human-readable heading (framed by pseudo tags) and the pseudo index markers.
  5. A paragraph containing a link.
  6. Other “content” paragraphs.

Code of a topic before cleanup

In a series of sweeps through the project using Flare’s Search-and-Replace feature, I made these changes directly in the code:

  1. Deleted <title> tags, which I did in preparation for the TOC cleanup.
  2. Deleted style sheet links so that, later, I could associate the style sheet with the project.
  3. Deleted headings based on filenames, which I also did in prep for the TOC cleanup.
  4. Replaced pseudo heading tags with real heading tags so that <p>[h2] became <h2> and [/h2]</p> became </h2>. Similarly, replaced pseudo index markers with real index markers. (Excuse me for not including the details here; I think you get the idea.)
  5. Replaced other pseudo paragraph tags with real paragraph tags so that, for example, <p>[accessno] became <p class=”accessno”>.
  6. And so on.
After prototyping this first of 70 Flare sub-projects, I switched to a different tool to clean up the code: FAR HTML. With that tool, I could design more sophisticated search-and-replace routines and, with the Flare project closed, could execute them as a batch—in seconds. I could also save those routines in a file so that I could quickly execute those same routines on the other eventual Flare projects.

Step 8: Clean up the TOC

The last step was to clean up the TOC.

Working my way top-down, I could now simply drag-and-drop a topic from the Content Explorer to the TOC, nesting it as needed. Notice that Flare used the human-readable heading for the wording of the TOC item. (That’s because I deleted the <title> tag and the heading based on the filename.) All I needed then was to delete the original filename-based TOC item.

Cleaning up the TOC in the prototype Flare project

So what did we end up with?

You may be wondering what the output from the final Flare project looked like.

After all the other work that goes into developing a Flare project (e.g., setting up the master page, defining styles, editing the skin, setting up search filters) was complete, the final output looked like this:

Output generated from the finished Flare project

Did prototyping outside of Flare really save time?

Absolutely!

Once the prototyping workflow was perfected, an assistant and I could prototype additional Flare projects quickly. We could go from empty mind-maps to well-structured Flare projects containing topics with actual content (or at least placeholder content)—within just a few hours, each.

Prototyping with a mind-map is more than just a time-saver. It also helps me to be more creative when planning the architecture of a Flare project. By resisting the urge to design on-the-fly in Flare, I can concentrate—without distraction—on the structure of an eventual output, from the end-user’s point-of-view.

Once the structure is designed, the mind-map can be shared with reviewers, thereby avoiding costly rework down the road. From the approved mind-map, I can quickly get all of the topic filenames in place and can seed topics with content. All of this important work before ever cracking Flare open.

Looking ahead

In a future post, I’ll discuss how I can use Microsoft OneNote to prototype the same Flare project used as illustration in this article.

Let me know if you try using mind-mapping—or perhaps some other tool—to prototype your Flare projects. Happy designing!

© 2013 Nita Beck. CanStock photo used under license. Based on “Rapidly Prototyping a Flare Project,” which I presented at the MadWorld Learning Conference in April 2013. CanStock photo used under license.

Share
2 Comments
  1. Looking forward to the OneNote article. That product is one I have not delved into, and at a glance it is not drawing me in. =)

  2. I use OneNote every day, for all kinds of things, both professionally and personally. I used to keep lots of printouts of things in different colored binders, to keep all my clients’ various projects nice and orderly. I realized recently that I haven’t used those binders now for several years, since deciding to use electronic notebooks (in OneNote) instead. I especially like that I can view and edit my OneNote notebooks with the locally-installed app, with the iPad app, with the iPhone app, and … if I don’t have my laptop, iPad, or iPhone with me but I’m at someone else’s computer with access to the internet, I can edit my notebooks using the OneNote web app…. But I digress. I’ll reveal all soon about how I could have used OneNote instead of a mind-map to prototype the same Flare project.

MAD Certified in Flare

MadCap Advanced Developer (MAD) certified in Flare since 2009

Latest Posts

Bad Behavior has blocked 144 access attempts in the last 7 days.