Browse Sequence in MadCap Flare

A browse sequence is great if you have several topics that you want your users to view in a specific order. For example if you have a series of getting started content or recommended workflows, a browse sequence comes in handy. What happens is, when users view the compiled online Help system, they can use your browse sequences to “browse” through the topics  in order.

In a browse sequence, you can create books and links to topics, tables of contents, other browse sequences in your project, and movies. You can create these sequences manually or automatically in Flare. In this post, we’ll take a look at the manual option.

Creating a browse sequence for your online content

  1. Add a browse sequence to your project.
    1. Select Project>New>Advanced>Add Browse Sequence. The Add file screen appears.
    2. Name your BS and click Add. Your new BS opens.
    3. Once you create your BS, it is stored in the Project Organizer in the Advanced folder.
  2. Add your topics to the BS in the order you want them viewed by your users. The Browse Sequence Editor works just like the TOC editor. You can create new content from here or drag and drop existing content from Content Explorer. Using the New book option in the editor, you can even create books if you want to create a series of sequences. For example, we use these to create workflows for a large application that houses several modules. Using the book option, we create a workflow for module 1 the includes several topics representing our recommended workflow for that module. We do the same thing for the other 10 modules in the application.
  3. Once the BS is created, you need to enable it in your skin.
    1. Open the skin.
    2. On the General tab, select the Browse Sequences check box.
    3. Open your target and go to the General tab.
  4. Now you need to associate the skin and the BS with your target.
    1. Open the target and on the General tab and locate the Browse Sequence field.
    2. In the drop-down, select the BS you want used in your output.
    3. Select the Skins tab and make sure to select the skin in which you enabled the BS.
  5. Save the target and build.
Advertisements

Leave a comment

Filed under Uncategorized

Content Strategy Q&A with Kristina Halvorson

I attended this Q&A hosted by Gather Content yesterday afternoon, and as with all Kristina Halvorson encounters, I learned some good stuff.

  • Importance of video-specific content strategies with a strong focus on consistency in word choices, voice and tone
  • Observations on “plain language”
  • Conflation of Content Strategy and Content Marketing – in a nutshell Content Marketers discover their content marketing isn’t working and in trying to figure out why decide a content strategy is needed.  Halvorson’s take – “That to me is hugely backwards.” This entire section of the Q&A is fascinating and alone worth the time of attending.

Here’s a link to the recording. In addition, host Robert Mills provided links to some of the resources mentioned during the talk.

Leave a comment

Filed under Content Strategy

How to Architect Your Content Strategy

Last September I participated in the 2016 Content Marketing World conference – a great conference hosted in my hometown of Cleveland, OH. Presenting at the conference was a wonderful experience, and I thoroughly enjoyed being an attendee as well. I came home with lots of great information and my head teeming with new ideas.

A few months ago, the Content Marketing Institute published an article on my presentation – How to Architect Your Content Strategy – that I thought I’d share.

Let me know what you think…

http://contentmarketinginstitute.com/2017/01/architect-content-strategy/

Leave a comment

Filed under Content Strategy, Uncategorized

Automate Building & Publishing in Flare

If you’re like me, you have several Flare targets that you need to build and publish with some regularity. Our solution has been to use Flare batch targets to identify these targets then create a .bat file and use Windows Task Scheduler to set dates and times to run and publish the builds.

Thanks to a recent addition to Flare, we can now skip the .bat step and set Task Scheduler from the batch target in Flare.

  1. In the Destinations folder in Flare’s Project Organizer, create a destination for each publishing location.
  2. Create all necessary targets, making sure to set the publishing destination on the Publishing tab.
  3. Create a batch target
    1. Right click on the Targets folder
    2. Select Add Batch Target. The new batch target appears, displaying all targets in the project.
  4. Locate all targets you want to build and publish at the same time and select the Build and Publish checkbox for each.
  5. Select the Schedule tab in the Batch Target Editor.
  6. Click New and enter the days and times you want the selected targets to build and publish.

Leave a comment

Filed under MadCap Flare

Creating Glossaries – Step 2

Once you have your glossaries in place, you now need to include them in your output. This blog post covers how to include glossary content in your print and online output.
Enable Glossaries in you Skin file
  1. From the Project Organizer open you skin file.
  2. On the General tab, click the Glossary check box.
  3. Save your work.
Set Print output
In our case, we create a Glossary topic and add it to our Print TOC. Let’s cover this process first.
  1. Create a “Glossary” topic in Flare.
  2. Open your new topic.
  3. In your <h1> tag, enter the word “Glossary.” Hit enter.
  4. On the new line, select Insert > Proxy > Insert glossary proxy. You should see a gray bar with the text “output glossary proxy.”
  5. Add this new topic to the end of your output TOC.
  6. Save your work.
Next, let’s set up our print target.
  1. For Print output, open your print target.
  2. Go to the Glossary tab.
  3. Your options are:
    1. Do not convert termnone of the glossary terms convert to hyperlinks, popups, expanding text, or footnotes in the output.
    2. Convert only marked terms: only glossary terms that were inserted into topics as glossary term links convert to hyperlinks, popups, expanding text, or footnotes in the output. Glossary terms that happen to exist in topics as normal text will not be converted.
    3. Convert first occurrence of termonly the first occurrence of a glossary term in a topic converts to a hyperlink, popup, expanding text, or footnote in the output. This includes terms inserted as glossary term links, as well as glossary terms that happen to exist in topics as normal text.
    4. Convert all occurrence of termevery occurrence of a glossary term in a topic converts to a hyperlink, popup, expanding text, or footnote in the output. This includes terms inserted as glossary term links, as well as glossary terms that happen to exist in topics as normal text.
  4. Because we want our terms to display in only the Glossary topic we created, we select the Do no convert term option. NOTE: If you convert terms, all linked terms will be added as footnotes to each page housing a glossary term.
  5. In the Glossary file box, make sure the glossary you want used for this output is selected.
  6. Save your work.

Generate output WebHelp/HTML5

We will use the Popup style for our help links. This is the default option in Flare, so you do not need to assign a style option when creating the glossary links. If you are interested in a different style, see the Step 1 blog post.

  1. Open your help target.
  2. Go to the Glossary tab.
  3. Select Convert all occurrences of term. NOTE: This does not mean Flare makes all occurrences glossary entries. You still must complete the Identify/Link glossary terms procedure for each term you want linked in your output.
  4. Save your work.

Tips

  1. If you need to include a variable in your glossary term:
    1. Add the glossary link to the term without the variable inserted.
    2. Once the glossary term is in place, insert the variable where required.
    3. Open the glossary term and add the variable form to the term list.
  2. The glossary is an exact match for the term. Make sure to include all forms of the glossary term in the terms list to include the other iterations of the term.
    1. For example, if the term is “database,” make sure to also include “databases,” “Databases,” and “Database” in the term list.

Leave a comment

Filed under MadCap Flare

Creating a Glossary – Step 1

One of the great things about Flare is there are several ways to do just about everything; one of the not so great things about Flare is there are several ways to do just about everything. This was a huge hurdle for my team when we made the move to Flare four years ago. To make sure the entire team used a consistent workflow, several team members spent time testing the various workflow options available and selected the options we thought worked best. I thought I’d share with you the options we put in place for glossaries. This post addresses how we add glossary terms in our content. My next post will cover how to handle the glossary output.
Identify/link glossary terms
NOTE: By default, glossary terms will not be converted to links if they are found in any heading tags (<h>) as well as hyperlinks (i.e., content with the <a> tag). However, if the same term is found in, say, a regular paragraph, the term will be converted to a link in your online output. For your print output, you have a few options, that we’ll cover in a later post.
  1. Open the content file (topic, snippet).
  2. Highlight the word or phrase that you want to add as a glossary term and link. 
  3. Select Insert>Glossary Term Link. The Create Glossary Term dialog opens.
  4. If necessary, select the glossary on the right side of the dialog (you need to do this only if more than one glossary file exists in the project.).
  5. In the Definition field, type a definition for the term.
  6. Click OK.  The word or phrase is now shown as a linked glossary term with an icon  beside it. The term and definition are added to the glossary.
  7. To select a style class for your term, highlight the entire term – make sure to include tags around the term – and right-click. Select Class style and select your style. We use the pop-up style, which is the default.
  8. Save your work.
  9. If you want to make every instance of the word or phrase included in your project a glossary link, you can use the Find and Replace feature. For example, I want to link every instance of the word “database” to the glossary definition I just created.
    1. Select EditFind and Replace.
    2. In the Find what field, enter the glossary term. For this example, I’ll enter “database.”
    3. In the Replace with, enter the following:
      • <MadCap:glossaryTerm class=”Popup”>database</MadCap:glossaryTerm>
      • Make sure to change “database” to the term you are defining
    4. Under Options in the Find and Replace pane, in Find in, select (whole project) and select Find in source code.
    5. Click Start. You will have to review each topic before selecting Replace (do not run a “Replace in All Files). Glossary links DO NOT WORK IN HEADINGS, so whenever you encounter the word in a heading, skip that term by clicking Start. Whenever you encounter a location in which you do want to add the glossary link, click Replace.

Insert glossary term links for terms that have already been created

  1. Open the content file (topic, snippet).
  2. Select Tools>Glossary Terms. The Glossary Terms window pane opens listing all the terms already added to the glossary.
  3. In the Glossary Terms window pane, double-click the term that you want to insert as a glossary link.
  4. Make sure you double-click under the Term column. If you double-click anywhere else in the row (under the Definition or File column), the Glossary Editor opens instead. The word or phrase is now shown as a linked glossary term with an icon  beside it.
  5. Save your work.

Related Links:

MadCap Flare – About Glossiers

Leave a comment

Filed under MadCap Flare

Using Multiple MasterPages in Flare

I often hear folks complain about being limited to one MasterPage per target in MadCap Flare. Although it is true you can select only one MasterPage per target, you can, however, assign MasterPages at the topic level. For example, in my case I provide popup help in the UI, and for the popups, I don’t want breadcrumbs or a mini TOC. So I created a separate “PopUp” MasterPage that I assign to topics used for the popup help. Here’s how you do it.

  1. Create an additional MasterPage.
  2. In the Master Stylesheet associated with your output, right click on the HTML style and click “Add Class”.
  3. Give the new HTML class a name. This will be the style class used for the second master page.
  4. In the new HTML class, click “Show: Property Groups” from the drop-down and find “mc-master-page” in the “Unclassified” section.
  5. Set the mc-master-page property to the new masterpage you have created.
  6. Save the stylesheet.
  7. Open the Topic you would like to use the new MasterPage.
  8. Right-click on the HTML structure bar and select “Style Class” and click on the html.class that you just created.
  9. Save your changes and rebuild the target.
  10. Flare will use the new masterpage for any Topics associated with that html.class and the MasterPage you use in your target will respect the topic-level selections.

 

Leave a comment

Filed under MadCap Flare

Publishing in Flare – Best Practice Suggestions

I’ve recently had to look into best practices regarding the use of the Publishing feature in Flare, so I thought I’d share.

For those not familiar with this feature, Publishing allows you to copy your Flare output to selected destination. Getting the process in place takes a number of steps, all of which are nicely outlined in the “Publishing Out to Destinations” chapter in MadCap’s Targets Guide.

  1. There is no reason to include “Build destinations” on your publishing tab.
  2. The build destination is the destination set in the Output Folder field on the general tab – period.
  3. MadCap strongly recommends you build to a local destination. Building to a network destination will substantially slow the build process, the smallest network hiccup with kill the process, and the process with often error or time out, so in the end, no build/no publish.
  4. To build and publish with just one click, on the Publishing tab, make sure you have a destination created and selected, and then click Publish. If there is not an up-to-date build to publish, Flare will ask you if you want to build first. Just say yes and you’ve covered both processes with the one click.

Related Links

 

Leave a comment

Filed under MadCap Flare

Advanced Conditions in Flare

I finally got around to the Advanced Condition feature in MadCap Flare. I’m not sure why, but I was expecting this to be a lot more complicated than it turned out to be.

To give a quick overview, the basic method uses the top half of the user interface. You simply click “Include” and “Exclude” check boxes. The Advanced method uses the bottom portion of the user interface, and you have to create/edit the condition expression used to filter your conditioned content.

conditions

If you love writing expression statements, you can start from scratch here; if you’d rather just have to change the tokens controlling your “include” and “exclude” operations, I’d recommend starting with the basic mode, and once you have it set with your conditions and what you want included and excluded, switch to Advanced. You then end up with an expression statement for each condition, and you can simply change the tokens as needed.

NOTE: You can type the names of the condition tags as well as any of the following tokens: OR, AND, NOT, ( ).

For example, let’s say you have two output conditions: help and print. You also have four product conditions: A, B, C,and D. When working in the basic mode, an “Include” tag overrides an “Exclude” tag. So, if I have content tagged for product “A” and “help,” when I run my target to generate help for product B and I set my target conditions to include “help” but exclude “A,” this content tagged with both the “A” and “Help” tags will be included.

To fix this, if you look at your conditions in the Advanced mode in Flare, you’ll see the reason for this is Flare’s “Basic” condition settings use the “OR” token. To make the above scenario work, we’ll need to change to the “AND” token.

Basic mode expression:

Conditions.Help or Conditions.B or not (Conditions.A and Conditions.C and Conditions.D

Advanced mode expression:

Conditions.Help and Conditions.B and not (Conditions.A and Conditions.C and Conditions.D

This is just a simple example of what you can do with the Advanced condition feature, but it should give you a good idea if this option will fix any condition filtering issues you are having.

 

Leave a comment

Filed under MadCap Flare

A 21st Century look at Content Strategy

Most folks when they decide to talk about content strategy like to quote Kristina Halvorson of Brain Traffic, so here goes: Ms. Halvorson says a good content strategy, “plans for the creation, publication, and governance of useful, usable content. “ A great definition, but I always find this a little too high level. I want details, and for these I found Scriptorium’s Content Strategy 101.

In this book, the Scriptorium writers explain that a content strategy does not mean simply figuring out how to manage thousands of content-carrying topics or hundreds of chapter-bearing files. Too often this one element in the strategy becomes the entire strategy, but technical communication today is responsible for so much more. Just looking at the wide variety of deliverables my company provides tells you this is not your grandfather’s tech com: html-based help, pdfs, graphic-based help, videos, tip sheets, blog posts, articles, slide shows, UI text. Therefore, we should not be using our grandfather’s content strategy because not only does such a diverse library require talented writers and advanced tool sets, it requires a sophisticated strategy that manages both the source content used to create these outputs and the outputs themselves.

I’m sure this already sounds like a bigger chore than most of us expected, but unfortunately, we’re not done. We also must consider the outside departments. What is their stake in our deliverables, and how much say should they have in the process and the content? This may actually be the harder question and the most difficult element in our strategy, which explains why it is so often ignored, but if you ignore it, you really don’t have a strategy, and in my experience, this is the case with most tech com groups. What they call “strategy” is actually just a handful of “rules” that are themselves often ignored – because another important piece of the strategy is not in place: governance. But we’ll save that for another day…

Related links:

Leave a comment

Filed under Content Strategy