This is a presentation I gave at MadWorld 2019 in San Diego. Here is the slide deck from the presentation:
This presentation was given as an advanced workshop at MadWorld 2019 in San Diego.
You can download the project files and PowerPoint slide deck at the following URLs:
On Monday at 11:30am (Track 1), I’ll be presenting at the MadWorld conference in San Diego. The presentation is on setting up context-sensitive help in a MadCap Flare project.
Here is a URL to the SlideShare with the latest version of the PowerPoint:
Here is a project you can download to see what we worked on in the session:
On Wednesday at the MadWorld conference, I join forces with the indomitable Daniel Ferguson for a presentation on advanced TopNav output.
Session Description:
You already know that MadCap Flare is the best tool to help you create a great experience for your users when they engage with your help system online. What if you could make it even better? Turn those ideas into action by attending this advanced workshop where we’ll show you how to use bleeding edge CSS3 with complex selectors, pseudo classes and more to make your output “sizzle”. We’ll talk about how you can integrate JavaScript libraries like jQuery and Grunt to do more to make your output shine above the rest. Flare trainers Paul Pehrson and Daniel Ferguson join together in the workshop to not only show you what is possible, but to give you the tools you need to try it on your own. You’ll leave with specific ideas of things you can do in your current projects to make them better for your users.
In-Class Files
Click here to download the sample project and JavaScript files:
When you are working in Flare, you may have encountered an issue that drove me crazy for a long time regarding snippets.
When you have some content in Flare that you want to convert to be a snippet, usually you can just select the paragraphs of text and click the Create Snippet button on the Home ribbon. However, if that selected content contains certain types of content (I’m looking at you, tables), the Create Snippet button isn’t available. So what should you do?
One option is to select the content, cut it to the clipboard, go create a new snippet file, then paste the content into the snippet file, and finally insert the snippet into the original topic. Don’t do that anymore.
Instead, when you have the content highlighted, press the Tab key on your keyboard, and from the pop-up window, select “div”, then click OK. Now, click on the div structure bar. The Create Snippet option is now available! Click it to convert your div’ed content into a snippet.
Tip: If you can’t press the Tab key because you are in a table or a list, use the 
(group) button instead.
You can stop here if you want, or you can make the following additional change. In the new snippet file, right click on the div structure bar, and click Unbind, then save the snippet file. This removes the div HTML element from the content. It doesn’t hurt to leave it in; since the div doesn’t have an id or class it won’t change what the content looks like in the output. That said, there is no reason for it anymore, so you can delete it if you want to keep things clean.
There you go. It’s Wednesday, but we’re going to call this a #FlareTipTuesday anyway.
Hey all,
I’ve been talking with a good friend of mine about launching a Flare-specific podcast. We would include interviews with luminaries in the Flare community, tips and tricks in working with Flare, a broader discussion of technical writing in general, and other such topics.
To get started, though, I’m interested in hearing from you about what topics you would be interested in listening to. What kinds of questions would be best answered in a podcast format? Who are the people you’d like to hear from to learn their perspectives on help authoring, and on using MadCap products?
Feel free to submit comments to this thread, or you can use the comment form.
I look forward to hearing from you.
I had a recent comment on a post I wrote nearly ten years ago. The post actually earned me a bit of notoriety in the MadCap community. For many years after writing that post, people would see me at an industry conference and say, “Oh, you’re the guy who wrote The Six Things I Hate About Flare.” I would quickly correct them, telling them I was very careful at the time to not use the word hate. In fact, right after my actual post entitled “Six Persistent Flare Problems,” I quickly published a post on “Six things I loved about Flare.” I published in that order, because I wanted people to remember the great things I said about Flare, not the quirks that annoyed me. (Nobody ever commented to me about the latter post though, so that didn’t really go as planned.)
A lot has changed in ten years! As I reread that post I realized that ten years ago, I was using Flare version 3. Since then, there have been annual numbered releases, all the way to Flare v12. Then MadCap changed the release naming scheme, and moved to a year-based name, so we got Flare 2016 r2, which could have technically been called Flare 13, but now MadCap posts the year of the release, and if a new major release is released in the same year, they add the “r2” addendum so you can see what version you’re dealing with. That means with Flare 2017, there have been 11 major release of Flare since my “persistent problems” post ten years ago. That is a lot of time, and A LOT of new features.
Now I am using Flare 2017. For your sake, I hope you are using Flare 2017 as well. I’ve been using it since it was released in January, and I’m exceptionally satisfied with the new features in this release.
In the past, I’ve talked in detail about the new features in a given Flare release. I think in this post, I want to take a slightly different direction and talk about my overall satisfaction with Flare as a technical writing tool, based on over a decade of experience working with Flare, training on Flare, and presenting on Flare to large audiences around the world.
Let me state my opinion right out of the gate: MadCap Flare is hands-down the best help authoring tool I have ever used. Its list of features is extensive, and the breadth and depth of its features is vast. The power of Flare is in its ability to help you reuse content in many different ways. You can write once, and maintain content in one single location, and then use that content in many different ways for many different audiences. Here is a partial list of single-sourcing features in Flare 2017:
- Conditions – You can apply conditions to content, and then you can select a combination of include/exclude commands for conditions for each target that you build. (In the context of Flare, you can consider a target as a deliverable. It is a specific set of content published for a specific audience.)
- Snippets – You can reuse chunks of content endless times across your project by putting shared content into snippets, and then referencing those snippets when you need them in other topics. When you need to make a change, you open the snippet, and the content is automatically updated everywhere you use the snippet.
- Variables – Flare has support for several types of variables, allowing you to specify at the project level, or at the target level what the text of a specific variable should be. This makes it easy to create separate targets for specific customers where you can using the wording and terminology that is specific to that customer. Variables are also useful for items that may be used across the document, but may change over time, like the version number of the product you are documenting.
- Snippet Conditions – An advanced feature in Flare, snippet conditions let you customize a snippet for use in multiple places in the project where the content is similar, but not exactly the same. You can then edit the conditions that are used for the snippet at either the topic level (all snippets in that topic will use the specified condition), or at the point the snippet is inserted (allowing you to use the same snippet in multiple places in the same topic, but with different conditions applied.
- Snippet Variables – A fairly new feature, you can specify the variable text of a variable used in a snippet at the point of insertion, allowing you to set custom text at the point of insertion without having to specify the actual text in the variable definition, making it easier to use a snippet in multiple ways across the topic or project.
- Multi-channel publishing – A Flare staple since the beginning, the number of ways you can publish content is increasing over time. Flare now supports two flavors of HTML5 publishing, both a traditional tri-pane output and a new “Top-Nav” output that works more like a traditional website. Other targets include direct-to-PDF publishing, XHTML targets, DITA, Framemaker, and Word (to name the most popular).
- TOC-embedding – In my experience, this is an oft-overlooked feature in Flare that allows you to single-source your TOCs and embed a TOC into another TOC. This means you can update the order of topics in multiple targets by editing the sequence in one TOC, and all other TOCS that use that edited TOC will automatically update. When you are working in small projects, this may not be too important, but for clients with larger projects (many I’ve worked with have dozens of TOCs; my main current project has 80 TOCs) this is a real life saver so that content in various TOCs don’t get out-of-sync with each other.
- Project merging – In many writing shops, different groups of writers are working on different parts of a project, and at some shops, documentation may be created for separate projects that need to be merged into a single cohesive help system for customers. Flare allows you to merge project outputs, giving you that single system for customers.
- Screen capture tool that uses conditions and variables from your project – MadCap Flare ships a companion tool, MadCap Capture for free with each Flare license. Capture is a powerful tool that allows you to not only use conditions and variables in your screen shots (and they automatically get updated each time the project is built!), but it also keeps the content of the call-outs separate from the call-out itself, so you can edit call-outs, replace background images, and even translate call-out text easily at any point in the future.
- Global project linking – If you need to work in separate Flare projects, but you have a core group of files you want to use in all your projects (style sheets, master pages, glossaries, corporate logos, etc.) you can maintain those items in a ‘master’ project, and then you can link your other projects to that master project and import those shared elements. Any updates to the master project will get pulled into the other projects before the other projects are built, so they always have the latest-and-greatest versions of those globally-used files.
And that is just a list of Flare’s single sourcing features!
What else do I love about Flare? Lets talk about the user interface experience. Flare is designed with the technical author in mind, and has many, many features that make creating and updating content easy and efficient. For example:
- Customizeable user interface – Flare’s various windows and panels can be arranged in a virtually unlimited number of ways. If you have a wide-screen monitor or multiple monitors, you will especially appreciate Flare’s interface flexibility.
- CSS-based styling – This is huge. Flare uses CSS for styling both online and print output. While you don’t need to know CSS to use Flare’s editors, the work in the background is being stored in CSS, and you can get in and manipulate it manually, so any CSS you learn (or already know) will help you style your content the way you want in Flare. Can’t figure it out? Look at the literally millions of websites and hundreds of books on CSS to find your answer.
- Multiple editing views – One of the things I fell in love with in Dreamweaver many years ago was the split-screen view where I could see the code and the WYSIWYG editor at the same time. (This may be born of my love of ‘Reveal Codes’ from the old WordPerfect days.) Flare fully supports this. You can view just the WYSIWYG editor, or the text editor, or both at the same time. You can put the windows top/bottom or side-by-side. You can filter your current WYSIWYG editor by conditions, allowing you to see only specific conditions while editing. You can view your WYSIWYG window in print format (complete with pages based on existing page layouts in your system), or in web format (where you can even specify a specific media type). There are a lot of options, so you can work in the way that makes the most sense to you, based on the content you are currently working with.
- Dynamic preview – This is a new feature in Flare 2017, and I love it already. I have an extra-wide monitor, and I love having the preview of my content being updated in real-time while I’m working.
- Context-sensitive right-click – Depending on where you are, when you right-click in a topic you get a list of options. In a table, you get table-specific options. In regular text, you get different options. There are easy ways to insert links and cross references without necessarily looking at the entire list of your topics (a list showing, for example, all open topics, which can be quite useful in large projects).
- Drag-and-drop – When you need to insert content from the Content Explorer into your topic, in most cases, you can just drag the item from the Content Explorer and drop it in your topic. This makes it super easy to add content to a topic.
- Customizable keyboard shortcuts – Flare lets you create your own keyboard shortcuts for virtually every Flare function. I have keyboard shortcuts to apply specific styles, and others to run specific Flare macros.
- Quick search – The main project I work on is big. Really big. Finding a specific topic can be difficult. I can use quick search to find any file in the project quickly and easily.
- Quick-access toolbar – Like many Windows products, Flare lets me customize the quick access toolbar at the top of my screen. I can even select sub-options (like a numbered list) and put them on the quick access toolbar making it very easy to find and use them.
And this is just a very short overview of what Flare can do. We haven’t even gotten into context-sensitive help, reports, the link viewer, group reviewing options, and integration with source control (including MadCap’s own Central offering). In my organization, we have our Flare project connected to GIT, which is connected to buildbot, so every time we check into GIT, buildbot generates a command-line compiled version of our targets, and copies the resulting files to an internal web server. Our developers and help authors always can view the most-recent content on the internal website, making it easy to review and approve topics.
In addition, I’ve had the privilege of being part of the Flare community forums for many years. That is a great group of people with a wide variety of experience and expertise who are willing to help users with questions that they have. The community forums, in addition to Flare’s excellent support staff, make Flare a very attractive tool because there are willing people who want to help you succeed in your project.
Are there things I’d like to see added to or improved in Flare? Sure there are. For example, I’d love to see Capture profiles stored in the Flare project, so they are available to all team members. I’d love to see more robust content management options for replacing live content on a schedule. I’d like to see a browser-based content review tool (taking MadCap Contributor to be a cloud offering) — something that might make MadCap Central a more attractive offering for a wider user base. I’m frustrated with side-menus in TopNav outputs not being location aware (if you have multiple topics used in the same TOC, only one of them is generated into the output, so the sidebar navigation is only correct for the first place the topic appeared in the TOC). But these are all things I expect MadCap to continue to improve over time.
If we–from the outside–can judge based on the last ten years, it’s a pretty safe bet that there will be a lot of Flare goodness in store.
In the comments, tell me what features you think will be in Flare in the next ten years (Flare 2027(!), if the current naming scheme is continued).
Hey everybody,
The 2016 MadWorld Conference is now in the history books, and I’ve been asked to provide my content from my presentations here on my blog. I’ve created a page where you can view all the shared content from my presentations.
This year I was asked to participate in the Lightning Talk session. To be honest, I had a hard time narrowing down my topic until the last minute, so I didn’t have any slides prepared for that session. Instead, however, I’ve taken my topic–Using Browser Tools to Understand Your CSS–and I’ve turned it into a short YouTube video (you can see it at the end of the post).
I’ll write up a conference wrap-up post a bit later, but I wanted to get my slides and other content out there for you as soon as possible.
Here’s my lightning talk.
Today MadCap Software announced the call for papers for the MadWorld 2015 WorldWide Learning Conference. You can read more and submit your proposals on the MadWorld 2015 Conference website.
Update – March 17 2014 – The article I wrote for ISTC’s Communicator journal is now reproduced in this article on my blog.
I’ve been an early tester of Flare V10, so I’ve had my hands on it for the last couple of months, and I’m thrilled to be able to talk publicly about some of the amazing features in Flare V10. I have a forthcoming article in a European tech comm journal, and I don’t want to give away what is in that article, but today I want to take a minute to share with you some of my favorite V10 features.
First and foremost, Flare V10 has added responsive layout to the HTML5 target. This means that with minimal work on your part, your content can adapt to the size of the screen that is displaying the content. The Flare V10 HTML5 target includes media sections for different screen sizes, so when a tablet user views your website, they get a customized view for tablets, and when a smart phone user views your website, they get a further customized view for small screens. So, you don’t have to generate specific output for mobile outputs, which is a beautiful concept. You only have to produce one output, instead of three (computer, tablet, phone).
(Here is a hint: if you just upgraded to Flare 10 and want to see the responsiveness of HTML5’s updated output, there is a setting in the HTML5 target that you need to enable to build responsive output. In the Project Organizer, open the Skins folder, and open an HTML5 skin. On the Setup tab, there is a “Responsive Output” section. Check the box to enable responsive output. If desired, change the dimensions when responsive output is triggered. (This means any viewport/device with a resolution BELOW what you set will see the “responsive” version of the webhelp, and any viewport/device with a resolution ABOVE what you set will see the standard HTML5 desktop view.)
Flare V10 includes a new skin editor that gives you a lot of control over how your output will look at different sizes, with built-in live preview of the changes you’re making in the style editor. If you’ve used the Skin editor in earlier versions of Flare, you were probably like me: I would make a small change, then click the “Preview” button to launch the skin in a browser so I could see what it looked like. Thankfully those days are gone, at least for HTML5 users. You can now preview your skin changes live in the editor, which will make editing skins much faster and more convenient.
I’m quite excited as well about the new templates that are included in Flare V10. There are a wide variety of templates to choose from, including many non-traditional templates like multi-page spreads for pamphlets and such. I actually haven’t tested these out yet, but they look very cool.
This release of Flare also includes functionality to support more OTF fonts in various output types. This is great news, and will dramatically improve your ability to make your technical publications meet the Marketing Department’s design guidelines. I know clients who will begin using this feature, literally, this week.
Another feature I’m excited about is a little button in the XML editor that allows you to filter the XML editor window based on conditions. If you work with a lot of conditions, this feature is absolutely amazing. In one of my projects, I was actually creating content in snippets and applying conditions in the snippets, then importing those snippets into topics (with snippet conditions applied)—just so I could see what the topic looked like with only certain conditions applied. Now I can work in the topics themselves with and see just the content that will be included when I switch conditions. This filter is absolutely amazing, and for those of us who use conditions extensively, this is reason enough to upgrade to Flare 10.
There are a slew of other features to love in Flare 10, but this is a version I’d upgrade to, even if I had to pay for it myself. It’s a dramatic improvement in what was already an excellent product. When my article in the UK journal is published later this month, I’ll include a link at the bottom of this post.
So, what is your favorite feature in Flare 10? Let’s discuss in the comments below.