Technically Speaking

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.

The other day I was walking through a parking lot and I overheard one side of a phone conversation. The person speaking said, “I’m the link between the geniuses and the regular people.”

The comment floored me, because I think that is true about technical writing in general, and about my job at my company in particular. I’m amazed at what our engineers and linguists know and how good they are at developing our software. I work with some seriously smart people. They are fantastic at their job: developing our software. Then I get to come in and become the link between the geniuses and the regular people (i.e. everybody else). I get to make recommendations on improving the user interface to make it more intuitive and easy to use. Then I get to write the documentation that answers all the questions people will have about how to use the software. In a very real sense I’m the link between the geniuses and the regular people.

Have I mentioned that I love my job?

Have I told you lately that I love my job? Twice in the last year I’ve been approached by people who wanted me to investigate another work opportunity, and both times I turned the people down before they could get going. There are so many fantastic things about my job, that I can’t imagine switching into a situation that might not (how could it possibly?) be as good.

The company I work for has a very appealing corporate culture. There is a real sense of family unlike anything I ever expected from a job. I remember when our baby was born last December. I received flowers from the office, and the whole executive team (all but two of whom have offices in California, not Utah, so I don’t hardly know them) sent me individual e-mails of congratulations–the longest of which may have come from the CEO. The office has a dot-com startup feel with people wearing shorts and t-shirts, but the people I work with are exceptionally intelligent and good at their jobs. I’m surrounded by geniuses. I look around the office and think to myself, “I can’t believe that they picked me to work here.”

As for the work itself, it is fun and interesting. There is always plenty to do to keep me occupied. My manager is happy to let me experiment with new tools or other ideas to see how things will work and is supportive and encouraging. I have a lot of autonomy; as long as I get my projects done on time (I haven’t missed a deadline yet, in over a year), nobody is very concerned about where I work from, or what my hours are. I put in a lot of hours near my deadlines, but I’m able to be much more flexible when I’m not at the end of a development cycle.

I feel like they trust me, believe in me, and need me, and are genuinely pleased with my work. There’s no wonder why I love my job. And no wonder why I won’t consider leaving. It may not get any better than this. And a million people would die to love their jobs like I love mine.

So ACME (generic name for the company I work for), this month we celebrate a year working together. Raise your glass as we look forward to many more.

Yesterday I made a comment on Tom Johnson’s blog, I’d Rather Be Writing. A couple of months ago, Tom posted a list of ten reasons not to upgrade to Adobe’s Robohelp 6. (RH 6 is a help authoring tool (HAT); for those of you who aren’t technical writers, a HAT is a program that technical writers use to produce help documentation, either printed or online.)

Well, yesterday a reader named Richard posted a comment, asking Tom how long he had been working for MadCap Software, the authors of Flare (another HAT, which is a direct competitor to, and in some ways a descendant from, Robohelp). My response was to the effect that not all Robohelp critics work for MadCap, and not all Flare critics work for Adobe. I’m a Flare user, and I’ve found several bugs and problems with Flare that I think new users should be aware of before they pick Flare as their HAT of choice.

Tom responded asking for a list of problems I’ve found with Flare. This inspired me to write a full post on the problems I have encountered with Flare in the 6 months I’ve been using it.

Now I want to be really clear here on a couple of points: I don’t work for any HAT vendor. I’m not affiliated with any HAT vendor. That said, I use Flare as my primary HAT, and I really like it. I think Flare is a powerful tool that, for the most part, does exactly what I want a HAT to do. My list of problems with Flare is NOT a list of reasons that you should not consider Flare when evaluating a HAT. It is, in fact, a list of problems I’ve encountered as I’ve tried to use Flare in a real-world scenario. Some of these problems have easy solutions. Some of them don’t. Some of these problems are universal to all users, while some of them are specific to my help projects. Your mileage will vary.

Additionally, if you know nothing about Flare, then you should know that Flare is a fairly new HAT. It is XML-based, so all the source topics are stored as XML-compliant files which makes documentation management wonderful. Flare allows you to publish to multiple “targets.” One target might be a Word document with a table of contents, a foreward, headers and footers on every page with a printed glossary and index at the end of the book. Another target might be a different Word document with only some of the topics from the source project. This works if you produce two versions of your product, say a professional version and a “lite” version. A third target might be computer-based help (like you get when you press F1 in Microsoft Word) for your professional version. In the computer-based help version, you want different headers and footers (maybe breadcrumbs to show where you are in the overall help project), and you don’t want the same TOC, Index, Glossary, or even fonts as the printed version. A fourth target might be your computer-based help for the lite version.

When you get the projects set up with the styles for printed and computer-based targets, publishing to them is very easy. At the click of a button, you can create all four versions of your help from the source XML files. It is a powerful idea that works quite well, for the most part.

If you are considering Flare as a HAT, you really owe it to yourself to make good use of the 30-day free trial available from MadCap Software. The trail version is fully functional, but it will munge your outputs so you can’t use it professionally until you have purchased a license key.

With that said, stay tuned to my next post for my top problems with MadCap Flare. Then next week, I’ll post a list of the top things I absolutely love about Flare, which in the end, is a great HAT.

Remember the tale of the boy who cried wolf?

Quick recap: Shepherd boy who thinks it will be funny to yell out “WOLF” at the top of his lungs to see what kind of reaction he can get from the villagers. As he hoped, they come running to defend the sheep. When they find there isn’t a wolf, they reprimand the boy and go back to the village. A second time, they boy cries “WOLF” and the villagers come running. And again, the boy is chastised and the villagers return home. Later, a real wolf is stalking the sheep, and urgently the boy screams “Wolf! Wolf!” but nobody comes running. The story ends with an old man telling the shepherd boy, “Nobody believes a liar, even when he is telling the truth.”

How many fire evacuation drills have I been through in my life? They started in elementary school and continued throughout my educational years. Even in college I was in buildings that were evacuated due to non-emergencies. Every time, it has been like the boy crying “Wolf” just to get a reaction from the villagers.

I’ve stopped responding. Two years ago at my office building there was another fire drill. In that company, we had a specific meeting point across the street where we checked in with our manger, who followed specific safety guidelines from the corporate emergency response book. I thought it kind of ridiculous that grown adults still needed to go through fire drills like we were all still in kindergarten or something.

Thus, when “Wolf” was cried yesterday at work, I wasn’t too concerned. I didn’t realize that a wolf was prowling at the edge of the herd of sheep. I was in the break room when the alarm went off. On my way back to my workstation, I saw my supervisor and asked where we were supposed to meet in an emergency. His (not-so-helpful) answer was “outside.” Back at my desk, I casually synced my iPod, logged off my computer, unplugged it, packed it in my work bag, retrieved my mobile phone from the charger, turned off my light, and grabbed a Diet Coke and an orange from the fridge. THEN I joined the crowds of people still evacuating the building in the stair well.

We were behind a woman who was having difficulty descending the four flights of stairs. Well, she was doing okay, she was just slow. Some guy about a half flight of stairs above us made the comment, “A lot more people were killed in the World Trade Center in the stair wells than in the elevator.” (An interesting observation, to be sure, but it also fits into the ‘not-so-helpful’ category of things said yesterday.)

Finally we got outside where I saw a couple of my co-workers. From our exit, we couldn’t see anything that would have prompted an evacuation of the building. One of my colleagues suggested walking around the building, to the north side, to get out of the sun. I followed him around the corner, where we could see a firetruck about a block ahead. Curious, we continued walking to see what was going on.

At the intersection, we saw one of the fire fighters preventing somebody from going into the parking garage, saying there had been a massive gas leak a half a block east of where we were now standing. The fire department was closing the area, and everybody needed to move one block north or south of the leak location. (We, unwittingly had been walking in the wrong direction.)

We continued walking to the north end of the Gateway, and turned east. As we got to the next corner, we could smell the gas. It was terrible! I crossed the street heading east and walked into the TRAX station. I wasn’t too keen on getting on an electric-powered train near a gas leak, so decide to keep walking to a later TRAX station.  As I walked parallel to the street with the leak, I could smell the gas from over a block and a half away, and the stench was overpowering. As I got back to street my office building is on, I looked west and could see that the workers in my building were still not being allowed back into the building. So I just walked to Gallivan Plaza, where I boarded a train for home.

As I waited for the train, I powered up my laptop and read the breaking news stories on the gas leak. Turns out the situation was a lot more dangerous than I realized, and I probably shouldn’t have been so casual about my response to the fire alarm.

Its just hard, because nobody believes a liar, even when they are telling the truth.