Technically Speaking

Yesterday MadCap released the first public beta of Blaze — a new authoring tool for creating printed output. Blaze is targeting to compete in the same space as Adobe’s Framemaker application.

I’ve seen Blaze in action during a demonstration done by Sharon Burton, MadCap product manager. During that demonstration, she showed us some things that I was really excited about, but wasn’t sure I was allowed to talk about. (As a MadCap MVP, I occasionally get to see some things that require me to sign a non-disclosure agreement. I wasn’t sure if what I saw in the demo was covered by the NDA, so I decided not to say anything.) Now that Blaze is in beta, I feel like I can talk about what I saw.

Now I have to admit that when I was “watching” Sharon’s presentation on one computer, I was busily working on another computer trying to meet a deadline, so I didn’t give the presentation my full attention. Maybe because of that, when I installed the beta of Blaze yesterday, I wasn’t ready to be wowed.

Blaze wowed me.

I know that Blaze and Flare share the same code base, so I expected Blaze to be a watered-down Flare 3. It’s not. I’m still working my day job, so I haven’t had a ton of time to churn through all of Blaze’s new features, but I’m really impressed with what I’ve discovered so far. Here are some of the highlights:

• Direct publishing to PDF
• Topic Review capabilities
• Master Page Layouts
• Layout modes in XML editor (with zoom view)
• PDF Preview
• Reports in Blaze
• Project Zipping

I’ll treat these one by one below. Again, a general disclaimer, I haven’t spent tons of time putting each of these features through the ringer; and these are just the ones I discovered while tinkering, (not reading any documentation on these features).

Since Blaze features are a sub-set of Flare features, you can safely assume that what makes it into the Blaze final release will make it into the Flare 4 final release. But there is always a chance that some of the features that are in the Blaze beta won’t be in the final when it is released for sale.

Direct publishing to PDF

This feature alone is enough to make me upgrade to the next version of Flare. The first thing I did after installing Blaze was to manually convert one of my Flare projects into a Blaze project (there is no Flare importing tool because if you have Flare you won’t need Blaze). I knew that my master pages wouldn’t work the same way in Blaze, so I spent a couple of minutes creating a master page for my Blaze project, then I published to PDF.

I was astounded at the results. MadCap has fixed several problems I was encountering when I published my Flare projects to Word (a requirement in Flare 3 and older in order to get PDF; To publish directly to PDF in earler versions you had to have Framemaker or Word installed. Flare created a Word/Frame file and let Word/Frame take care of the PDF creation). When I publish my Flare 3 project to Word, there are several post-processing steps I have to do in order to make my content look the way I want to. These have been fixed in Blaze, and my output looked stellar. I didn’t get everything right on my master page layout the first time, but I don’t expect to. It took me several hours of fiddling with my Flare master pages to get exactly what I wanted in my output, so I expect to spend comparable time in Blaze getting the master pages to do exactly what I want.

I noticed that my page numbering was off in my Blaze output; it turns out that MadCap has updated what I thought was a bug in earlier versions of Flare: you couldn’t set your page numbering settings on the topic in the TOC. You had to do this in the master page. Blaze now has a pages setting in the properties setting for a topic in the TOC. (Blaze calls the TOC an outline. Outlines in Blaze are TOCs in Flare. I asked Sharon about this during the Blaze demo, and she said that there were no plans to change the terminology in Flare, so if you are trying to learn Flare and Blaze, you’ll need to know that there are some areas where Blaze and Flare share functionality, but have different terms to describe the functions.) This is exciting, as now I won’t need to have separate master pages when I want to change the numbering options in my document.

Anyway, the direct to PDF option knocked my socks off. I’m absolutely thrilled with this feature. I can’t wait to use it in a production environment in Flare 4.

Topic Review capabilities

Blaze introduces the ability to do topic review with an annotation system similar to comments in MS Word and Adobe PDF files. To review a topic, the user opens the topic in the XML editor, then changes to Review mode.

I can add annotations about a topic, which are stored in the XML itself. The difficulty for me in using this feature is that I couldn’t find an easy way to add an annotation. I discovered that you are supposed to right-click to add an annotation, but I’d like to be able to click and start typing (since you are in review mode, it’s not like you can do editing anyway; this would be kind of like how Word tracks changes). Finally I found the add annotation button on the tool bar, but this took me a long time.

If your reviewers don’t have Blaze or Flare installed, MadCap is introducing a new product called X-Edit Express — a free tool your reviewers can use to review, make suggestions and light edits, and submit back to you. All my SMEs can install X-Edit Express, and I can use Blaze/Flare to submit the file to them for editing. They open it in X-Edit Express, do their review, and click Save. The file will show up again for me as being reviewed. I can open it to see what changes/annocations they made.

X-Edit Express isn’t available for review yet, but I’ll give you my comments on that one once I’ve had a chance to evaluate the program.

Master Page Layouts

Since Blaze is a product for print documents, users need a solution for creating high quality master page layouts that might have multiple columns, or different layouts across different pages. In short, to compete with FrameMaker, Blaze needed to provide great control over page layout.

I love the new Master Page Layout editor. I haven’t spent a lot of time working on this page, but I think it seems very powerful, and I can see how this would allow me to create some very high quality printed output. The possibilities here are endless.

Layout modes in XML editor (with zoom view)

The Blaze XML editor includes the ability to look at your document using the Print layout. This basically means that you see your content using the printed master page already applied. You see your headers, footers, and columns (if you have multiple columns on your master page).

The Print Layout mode includes a zoom view which provides a view like FrameMaker or QuarkXPress users are used to seeing with your rolling page layout, which allows you to see facing pages while you scroll through the document — while allowing you to edit content. This is an editing mode, not a preview mode. Framemaker users and QuarkXPress users may find this the most comfortable view for editing, as it will look more like what they are used to seeing.

I’ll be interested to see how I like this feature as I’m working in my Blaze and Flare projects.

PDF Preview

The preview feature in the XML Editor (in Flare) has always shown you the the preview based on the primary target. Since my primary target in Blaze is PDF, the preview button generates a PDF of the current document and shows you that. I was impressed.

Reports

Blaze (and thus Flare 4) includes a number of reports that you can run on your project helping you identify many things including (but not limited to) the following:

• broken links
• bookmarks
• duplicate styles
• new style suggestions
• local styles
• snippet suggestions
• topics not in index
• topics not linked
• undefined condition tags
• undefined glossary terms
• undefined styles
• undefined variables
• unused styles
• unused images
• variable suggestions
• … and many, many more.

The MadCap forums were ablaze (pun intended) with complaints when Analyzer was released, saying that the reports in Analyzer should be included in Flare. Well, it looks like many of them will be, based on the Blaze preview.

Project Zipping

Blaze includes a new Zip menu. This allows you to zip all the files in your project into a package that allows you to send your entire project to another user in one compact file. You might use this if you are zipping your project to send it to MadCap support, as part of a maintenance inquiry. I used it to share the project from my dev box to my laptop. I imagine you would also use this if you wanted to send your project off for language translation (which would be easy if your translator used MadCap Lingo for translation).

It’s not huge, but it is a nice feature that I’ve already found use for.

Summary

All in all, there is a lot to like about Blaze. I’ll continue using it and I’ll let you know what gotchas I run into as I’m using it. But based on my inital response, I can’t wait for Flare 4. There is so much that MadCap seems to have gotten right with Blaze. I’m very, very impressed.

(Want to get a sneak peak of Blaze? Go to MadCap’s website to request inclusion in the beta experience.)

There are several buttons in the Flare tool bar that I’ve ignored until now. Two I learned about yesterday in the MadCap forums, and another I discovered on my own. (I decided it was time to figure out what all the buttons do.)

Here are the buttons and their descriptions:

•   Locate in TOC. This button is available when you have a topic open in the Flare XML editor, or when you have a topic selected in the Content Explorer. When you click this button, Flare will find every instance if this topic in any TOC in the project. A list of TOCs will be shown. Click OK to open the TOCs with the topic highlighted.
• Locate in Content Explorer. This button is available when you have a topic open in the Flare XML editor. When you click this button, Flare will find this topic in the Content Explorer and select it. This will help you find the file in your file structure. This can be helpful if you open a file from a link, and want to see where the file actually exists.
• Send To. This button is available when you have a topic open in the Flare editor. When you click this button, Flare will display a list of external applications that are associated with the file type that is currently open in the Flare editor. (This is the same list you see when you right-click on a topic in the Content Explorer and select the “Open With” option. This is an easy way to open a topic in an external editor if you need to make changes to the underlying XML code.

Enjoy!

Last week I was interviewed by Tom Johnson for the Tech Writer Voices podcast.

Here is the link to Tom’s podcast post. He’s allowed me to embed the podcast here on my website, so you can listen to it from here if you’d like.

From Tom’s site:

Topics Discussed in this Podcast

* Flare’s XML editor
* Integration of Flare with source control
* How Madcap addresses the entire writer’s workflow
* Generating quality printed output from Flare
* Cross-platform shortcomings
* Thorough integration of CSS standards in Flare
* Flare’s CSS editor
* Flare’s learning curve — how long it takes to learn Flare
* Variables and snippets
* Indexes and insertion of index keywords within topics
* Implementing variables across the entire workflow
* Rewards from being a forum volunteer and moderator
* Madcap Software’s family feel
* Relevance of company size and location
* Mike Hamilton, vice president of product management
* Lingo and the single sourcing of content across images, topics, and outputs
* Lingo’s efficiency with localization
* Madcap’s responsiveness to blog comments and feedback
* Feedback Server and topic-based comments
* Balancing complexity with usability
* Madcap Analzer and Feedback Server
* Product/company image generated by blogs and user forums
* The online help market in 5 years
* Reasons for Framemaker’s stagnation
* Qualities of companies that will succeed in the future
* The best way to learn Flare

For those of you who are interested, today I released a new version of my online work portfolio. The content is pretty similar to the old portfolio, however there is a totally new layout and the back end is completely different.

I’ve migrated my entire portfolio site to use MadCap Flare. I know that Flare is usually considered a help authoring tool, and an online portfolio doesn’t really fit into the category of help, but I decided Flare was the best tool for my project because I wanted the following:

• Multiple outputs. An online portfolio is great, but the truth is that often times when I need to present my portfolio, I am going to want to be able to provide it in a hard-copy version. Since my source files are in Flare, I can create one target that publishes my portfolio to my website and another target that publishes it to a Word or Framemaker document.
• Output conditions. Ideally a portfolio is customized for a specific situation. Since my source content is in Flare, if I want to create a customized version of my portfolio for a particular audience, it is as simple as adding conditions to my topics, and creating a new target. In addition, if I don’t want to include links to my resume or writing samples, I can create one output type that excludes this information, and another output type that includes it. I can publish the limited-info version on my website, but publish the full-information version to a CD that I can give to people.
• Resume single sourcing. This part isn’t complete yet, but I realized that on my old portfolio site, I had several different versions of my resume that I was always updating to keep them current. That was kind of a pain, plus I had to keep all versions of my resume behind a “locked door” so-to-speak, as to keep private information private. With Flare, I’ll be able to create one version of my resume, conditionally exclude private information for the website, and create as many outputs as I need–all from the single file.

You’ll notice that my new site doesn’t have the frameset that is a standard part of Frame’s WebHelp output. I didn’t need the frameset because I don’t need the same functionality as I would for a help system. I could have modified my Flare skin so that the tool bar was only 1 px high and the sidebar was hidden by default, but that still loaded the site in a frameset, which I didn’t really like, so I set up HTTP redirection to take you directly to the topic page.

If you are interested in how I created the layout, I did all the layout in a Master Page. The layout is entirely CSS-based (as opposed to using tables for layout) which makes the site more accessible and standardized. (If you know how, try disabling the attached style sheets to see what I mean.) The images were all added to the style sheet, but I ended up inserting the banner image into the template’s HTML file so I could do an image map (which makes the words on the right side of the image links to the various sections).

In the end, I’m pleased with the new site. It gives me the flexibility to publish my portfolio in multiple media types with slightly different content for each target while maintaining only a single source for all my documents. Flare was a great choice for this project, even if it is an unconventional use for the tool.

My friend Tom Johnson posted an article (new window) last week about the recent release of the Technical Communication Suite from Adobe including RoboHelp 7. I added a comment to his post, but it got kind of long, so I thought I’d post it here with slight modifications. The quotes in this post are quotes from Tom’s post, linked above.

I’ve taken a look at RH7, and I personally wasn’t all that impressed with it. As I’ve watched discussions on RH7 evolve for the last few months, my experience is that people who want to be wowed by RH7 are wowed by it. People who want to be pleasantly neutral are able to be pleasantly neutral. And people who want to hate RH7 find plenty to hate about it. Tom said:

This past month I’ve been heavily using the RoboHelp 7 and Captivate 3 components of the Technical Communication Suite. RoboHelp 7 offers some impressive new features: snippets, breadcrumbs, a pod-based interface that you can drag around, integration with Framemaker and Captivate, and so on.

So basically RH has come out with some of the stuff Flare did, and copied the terminology (”snippets” for example) just to compete. Not particularly innovative, in my opinion, especially when they are a couple of years late to the party.

RoboHelp 7 allows you to begin Captivate movies from within RoboHelp. That way you don’t have to keep re-importing the files each time you update them. […] I ended up deleting the RoboHelp-initiated movies and imported them manually instead (File > Import).

My response is: then how is this good? If you ended up importing them separately, then don’t you have to keep updating them?

Personally, I prefer the way Mimic works for referencing the Mimic project from Flare, then building the Mimic output when Flare is built. You can share variables across products so your Flare variables are available for use in Mimic. That is pretty cool. While Captivate has more features and is easier to use than Mimic, I think you’ll see Mimic improve as MadCap puts more dev time into it, and it is a project that seems be getting some more attention internally. It will be interesting to see how these compare in a year or two.

Later in Tom’s post:

You might also want to be careful about manually editing the css style sheet. […] I recommend using RoboHelp’s official style editor, and perhaps playing with the _ns.css stylesheet that RoboHelp outputs when you generate help.

I hate anything that requires post-processing. A tool that requires post processing for creating WebHelp is broken, in my opinion. I want to be able to build my target and publish it in the next step. (However, I give more allowance for printed output, because there are conventions in printed output that are currently hard to get from the available tools.)

Online Help Quality Plummets

It’s a bitter irony when a HAT vendor produces poor quality help for its products.

Tom then turns attention to importing Frame files into RH7:

Framemaker Import Groundbreaking But Irrelevant for Me
[…]
Flare is developed by a team that is experienced with help authoring, and—perhaps the most confusing distinction—Flare seems to support FrameMaker more thoroughly both for importing and exporting content than does RoboHelp.

It’s ironic isn’t it? MadCap’s product does better with Adobe’s own FrameMaker than Adobe is. But I don’t get how this is groundbreaking? I mean, Flare does this and does it better. In Flare you can round-trip your FM files. THAT is groundbreaking and innovative.

I believe this is indicative of a larger problem within Adobe: they purchase a product then get rid of the developers who understand the product. Adobe is having trouble updating and making Frame compatible with other Adobe products because it seems they don’t understand the code behind what it does. I also wonder if they really understand the RoboHelp code enough to update it to compete in the new space (now that it has to compete with Flare, AuthorIT, and others).

It will be very telling to see what happens in the next RoboHelp release. Frame 8 is bascially Frame 7.2 with a new UI and a couple of upgraded features. But there isn’t any competition out there pushing Adobe to make a better Frame. RoboHelp is now in catch-up mode trying to figure out how to emulate the innovative features in MadCap’s product suite. Now it is MadCap pushing the innovation envelope here. Will RH be able to maintain pace with MadCap’s one (or more) releases per year? Will RH be able to come out with new features that aren’t already in Flare? Maybe so, but RH 7 wasn’t proof of that yet. Again, it will be interesting to have this discussion in two years and see where the major players are at.

In Tom’s conclusion he states:

RoboHelp continues to ignore some major issues, such as the lack of character-level indexing and the formatting errors when you export to Word. Despite my complaints, I like many others have an affinity for the usability of this tool. It’s like an old pair of sneakers that has some new laces and polish. Maybe some new traction too.

With his conclusion, he supports my theory that those who wanted to like it do like it. Despite all the problems Tom enumerated in his post, he still have a favorable impression of RH–a tool he has used in the past with good results. I tested RH7, and I’m very glad my primary HAT is Flare.

But to each their own. If anything, I hope a healthy competition between Flare and RH continues because that will help both products improve. Frame is a great example of how a product can go stagnant when no outside competition drives the need for new changes and features.