Technically Speaking

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.

(This is part two of a five-part series dealing with content reuse in the Help Authoring Tool (HAT) MadCap Flare.)

Yesterday I gave an overview of what content reuse is, and why it is important, and who should use it. Today we are discussing a specific way MadCap Flare allows you to reuse content: variables.

I start with variables, because they are a simple concept that is probably quite familiar to you. Snippets, which we discuss tomorrow, are like advanced variables, so it is important that we have a basic understanding of variables first.

If you have worked in FrameMaker, or have done any programming, you are already familiar with the concept of variables. A variable is code that you insert in your Flare topics that gets replaced when the project is built (prepared for output; when you develop content in Flare, the content isn’t in a usable form until you build an output).

For example, you might use a variable in your project to represent the product name or version number. Every time you want to use the project’s version, instead of typing in the version number, you insert the version variable. When the version changes, you modify the variable in one location, and the project is instantly up-to-date. No more find-and-replace projects where you hope you catch every reference.

Suppose you have a product that gets re-branded and then re-sold. I once worked for a company that created portal software for educational institutions. Each school branded their portal. Using variables, you can refer to the portal name generically, and create a separate output for each client with their portal branding information in the variable settings.

So, how do I use variables in Flare? Keep reading.

Flare groups variables into Variable sets. They are accessed (or added) in the Project Organizer, in the Variables folder. By default, your project contains a variable set called “MyVariables.” You can right-click on the Variables folder to add a new variable set, or you can just double click “MyVariables” to open the generic set. (For starters, it is probably easier to just use one variable set, instead of trying to incorporate multiple variable sets. Multiple variable sets is an advanced topic, not covered in this series.)

By default, there are two variables in MyVariables: CompanyName and PhoneNumber. Click the New button to add a variable to the set. Click in the Definition cell to change the variable’s definition.

So if you want to add a variable for your product Name, you would do the following:

1. Click the New item button.
2. Click in the Name cell (on the word NewVariable). Replace NewVariable with the name of your variable (in this case something like ProductName)
3. Click in the Definition cell. Type in the variable definition (like ACME Explorer).

If you want to add a separate variable for the version number, you’d just repeat the steps, but change the variable name and definition.

When you are editing a topic, you insert your variable by using the Insert menu, and selecting Variable.

You’ll see two variable sets: MyVariables and System. The MyVariables set contains all the variables you’ve set using the process described above. The System variable set contains variables like Date, and page number (for use in printed output).

Select the variable set that contains your variable, then select the variable you want to insert. Click OK. The variable is added to the topic at the cursor’s insertion point.

There is your introduction to variables in Flare. I highly recommend that you use variables in place of all your content that may change from release to release. I use the following variables in my projects:

• Company Name
• Windows installation directory
• Linux installation directory
• Product Long Name
• Product Short Name
• Product version

And before I set you lose creating variables to your heart’s content I leave you with a word of caution: If you change a variable’s name after you’ve inserted it into a topic, the link will break, and the variable will no longer be updated in those topics that contain the old variable name. Once you’ve inserted a variable into your topics, don’t change the variable name. (Obviously you can change the definition; that’s the whole point. Just don’t change what you CALL the variable, or the variables that exist in your project will break, and you’ll end up doing some fancy find-replace to update/fix the problem. Think about what you want to name your variable, and then don’t change it after you’ve begun inserting it into your project!

Tomorrow I’ll be back with information on Snippets–basically longer variables that can contain formatted text, images, etc. See you then!

Day 3: Snippets

So it’s been a while since I posted much on Flare. For a while I wasn’t using Flare in my daily work flow; I’ve actually moved all new development on the four product lines I support into my Flare work flow, but we keep needing to go back and do dot releases on an older version of our software. When I thought it was only going to be one dot release, it didn’t seem prudent to move the source into Flare. Now we’re working on the FIFTH dot release. Seems I should have made the switch. Oh well.

Anyway, for about a month now I’ve been back using Flare full-time again, and I’ve really been enjoying some of the features in the 3.x line. I didn’t really delve much into them when 3.0 first came out, so many of the new 3.0 features I’m only starting to use now in 3.1.

In any case, here are my favorites so far:

Running Headers/Footers in Word Output

One of my big complaints about InDesign compared to FrameMaker was that InDesign didn’t have an elegant way of allowing running headers and footers in your printed output. A running header/footer means the header/footer’s content changes to reflect the section of the documentation you are in. So a running header might automatically contain the name of the chapter, and a running footer might contain the text of the most recent H1 or H2 style in the document. This makes the printed document much more accessible, easy to read, and professional.

Flare 3.1 gives you the option to use running headers and footers on your Printed Masterpages. You add a variable set to your Flare project that defines the heading styles you want to grab as the header/footer text, then you insert those variables into your Masterpages.

The result is exactly what I asked for. Then I found out, I didn’t know what I wanted.

See, the running headers/footers work great if you stick to a rigid format (a-ha! the structured authoring debate comes again!) in your document structure (e.g. H1 style for chapter title; H2 style for section heading, etc.). I thought I had done that. When I created my printed output, I realized that I have certain sections in my Flare WebHelp that I have as drop-down heads. The style of the drop-down heading matches my H2 style, so in the printed output, you can’t tell whether the WebHelp uses an H2 or used a drop-down head.

That works great for masking the non-standard structure, but Flare can either use the most recent H2 in the footer, or it can use the most recent drop-down head in the footer. I have to go back to my documents and re-structure them so they are all structured the same in order to use running headers and footers in my printed output.

I don’t blame Flare for that, though. I need to pick a structure and stick with it. It’s not Flare’s fault I’m using two different structure formats in different topics.

I give the running headers/footers in Word feature two thumbs up. Thanks MadCap!

Source Control Integration from within Flare

A new feature in Flare 3.0 was source control integration from within the Flare interface. This is a cool feature that I didn’t know I needed, but one that I like the more I use it.

Flare provides direct integration with Microsoft Visual Source Save and Microsoft Team Foundation Server, and provided third-party integration with other source control systems that use the MS SCC API interface. My documentation is stored in an SVN repository, so I had to purchase a third-party plugin to get Flare to work with my source control system. (I bought my plugin from PushOK software, a vendor out of Russia. It cost me 600 Russian Rubles, which came out to about 25 dollars. I’ve been using the plugin now for a couple of months, and it works fine for me.)

I have only a few complaints here: I wish Flare supported the most common formats natively, so I didn’t have to purchase the plugin separately. And I don’t love how for some actions (like moving a folder of topics to a different location in the tree) it seems that either Flare or the plugin checks in each change as a separate revision in the source control. (I suspect this is the plugin’s doing.) Also, I purchased the plugin for one computer I use for editing the project (my main computer) but I didn’t purchase it for my backup computer. When I edit the project using my backup computer, I have problems because the SVN connection settings are stored in my flare project file, so the project files on my two computers can’t match. I hate having to purchase an extra plugin just for the occasional use of the backup computer, so I’ll probably just ignore the inconsistent settings in my project files.

Basic Style Editor

One of Flare’s strengths is the CSS editor included in Flare. In the 3.x line, they’ve stepped things up a notch by including a basic style editor and an advanced style editor. (The advanced style editor is basically the same editor we’ve seen in previous versions of Flare. The basic style editor is a new concept in 3.x.)

The advanced style editor shows all the inherited and local styles and classes in the style sheet. It also shows all the properties available for the styles and classes and lets you change them. You have quite a bit of control over how much information is shown on the screen; You can limit the styles by group, and you can limit the properties list by grouping by type, showing only set properties, or even a smart list of “relevant” properties–properties Flare thinks you might want to change for that style.

Two areas for possible improvement are: (1) Flare still has a habit of modifying my CSS just because I opened it. Example: for some reason it doesn’t like the asterisk symbol in complex selectors (e.g. ul * ol), and any time I open my stylesheet in Flare, it replaces all my asterisks with a “\00002A” which I guess is code for asterisk or something. (2) There is a toggle button to switch between the advanced view and the simplified view. However, the toggle button text shows you the view you will see if you click that button. So, in the screen shot included here, you’ll see that the toggle button says “Simplified View” even though you are seeing the Advanced View. It’s not a big deal, but it makes for a slightly confusing interface. Not to mention that the Flare help system has to explain every time how to check to see if you are really viewing the advanced view or the simplified view. Simply putting the word “Show” in front of the text would really have made this easier.

Conclusion

I still love Flare. There is a learning curve to get up and running with it, but it is a very powerful tool that in my opinion just keeps getting better and better.

——-

PS: I suppose I ought to post a bit of news (and a sort-of disclaimer). Due to my activity in the Flare user forums, last month I was invited by Flare Support to be a MadCap MVP, and I accepted. I use the pseudonym “DocGuy” in the forums. This doesn’t make me a MadCap lackey; some MVPs are known for speaking their minds in opposition of perceived problems at MadCap. However, I am a volunteer forum moderator for the MadCap Forums, and I am a MadCap aficionado. But I don’t suppose that last bit is very surprising to anybody.