Tag Archives: Technical Communicatioin

July 23, 2014 · 8:17 pm

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 term: none 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 term: only 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 term: every 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

Tagged as , , ,

July 13, 2014 · 8:40 pm

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 Edit, Find 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

Tagged as , , ,

June 25, 2014 · 5:02 pm

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

Tagged as , ,

June 17, 2014 · 6:16 pm

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

Tagged as , ,

June 9, 2014 · 1:00 am

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

Tagged as ,

June 6, 2014 · 1:32 am

Moving from FrameMaker to Flare

A few months ago I did a webniar for MadCap on my company’s move from Adobe FrameMaker to Flare. We made the move for a number reasons – lack of support for FrameMaker from Adobe, FrameMaker was starting to look and feel “old fashion – but our primary reason for the move was we needed the granular control offered in a topic-based authoring environment, and FrameMaker did not offer that.

The webinar focuses on the following:

  1. Overview of the migration process
  2. How we prepared our FrameMaker content
  3. The import process in Flare
  4. Cleanup required in Flare after the migration
  5. How implementing MadCap Flare increased Blackbaud’s content reuse/single sourcing and allowed us granular-level control of output at the paragraph, topic, TOC, and target levels

If you take the time to watch it, let me know what you think or if you have any questions. We are in the middle of moving another large chunk for FrameMaker content into Flare, so the process remains fresh in my mind.

Watch webinar

2 Comments

Filed under MadCap Flare

Tagged as , ,

May 28, 2014 · 5:44 pm

Welcome to my blog

My goal here is to share what I know/what I learn about working in the world of technical communication. A good deal of my blog posts will be focused on the authoring/help-generating tool Madcap Flare, but that will not be the entire purpose of the blog. I will share information on the broader topic of the tech com field as well.

In this post, I would like to introduce myself. My name is Denise Kadilak, and I have worked in tech com for over 16 years. My responsibilities over this time have varied, from creating and maintaining 1000s of pages of user-end documentation; to something of a technical-project lead investigating new tools, best practices, and workflows for a 22-member documentation team; to my current position of Information Architect/Team Manager. Also, about four years ago, I led my team’s move from Adobe FrameMaker to MadCap Flare – a fun and intense time for everyone.

I also present with some regularity at industry conferences, such as WritersUA, STC, and Content Management Strategy and DITA, North American Conference. In January of 2014 I did a Webinar for MadCap on making the move from FrameMaker to Flare. You can watch the recorded version of the webinar here.
Finally, in addition to my full-time job, I am a part-time college instructor at John Carroll University in Cleveland, OH. I teach the Technical Writing course included in the school’s Professional Writing program.
I hope you find my topic and my credentials interesting enough to regularly visit this blog – maybe even to consider subscribing to it!

2 Comments

Filed under MadCap Flare

Tagged as , ,