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.

Blogging has become difficult recently. As I have worked at my new job, I’ve found that I’m running around from task to task at such a pace that I haven’t had much time for blogging. It’s a great thing, work-wise. It is interesting and engaging, which I love. It’s not so good for my blog. Last night Christina said, “I can’t wait to see your next entry.” Then she suggested that I set aside a specific time to blog, or I won’t get it done. Now, I’m on the train. I don’t have an internet connection, so this is a good use of my time.

I found a way to bring some light into the cave. I purchased a swing arm desk lamp. I can get it right up under my bookcase, over my computer. Now I can actually see what I’m working on, which is a benefit.

I am having a great time at my new job. I’m finishing the installation guide for the newest iteration of the company’s software. It’s about twenty pages long and I’m excited to get it finished… My first project.

From a technical writing perspective, I’m learning a lot working as a lone writer on a new project. First, It’s been interesting to try to figure out the resources I’d need to complete a project before I understood the scope of the project. I learned that scope is the horse, and resources are the cart that must follow. One of the first things the company wanted from me was a list of the software that I needed to get my job done. For my main document publishing tool, I was debating between InDesign and FrameMaker. The problem was that I hadn’t really looked at the software, nor had I seen the documentation requirements for the project. So I was working blind as I selected the software packages I needed.

I chose InDesign because I think it is a powerful publishing tool. And it came in a suite, packaged with PhotoShop, and Acrobat Professional, in addition to others. In the end, I was cheaper to buy the suite and get all the software than it would have been to buy just Photoshop and Acrobat Professional, so if you look at it that way, InDesign was free. The problem was that after I had ordered my software, I had a meeting with the product manager where for the first time I understood the scope of the project and understood the documentation requirements. It became clear quickly that some of the doc requirements wouldn’t be met by InDesign. In particular, InDesign’s support for the following features was lacking:

• Running Headers and Footers. The documentation template, which I am expected to use, has running headers and footers that reflect the heading levels in the document. So the document title always appears on right page headers. The chapter name always appears on left page footers. The text of the most recent Heading 1 always appears on the right page footer. InDesign doesn’t do running headers/footers, so I’d have to do these manually at the end of my production cycle — the very last step, for fear that the document might re-flow if any changes were added.
• Cross References. FrameMaker has a feature that lets you cross reference other headings in your book. So, if I was writing about a feature, and wanted to insert a reference to another chapter that deals with a corollary feature, I can insert a variable that pulls the heading text I want to point to, and the page that heading is on. If the document re-flows, or if the heading text is changed, the cross reference link is updated. So if I’m writing installation instructions, and I want to tell the user to see chapter 9 for more information on account management, I can enter a cross reference to do so. In InDesign, I’d have to just type the text in manually. If the chapter number changed, I’d never know all the places in the documentation that pointed to it.
• Conditional Text. The company I work for has government contracts and private contracts alike. There are certain documentation requirements for government contracts that we aren’t required to include in our regular product version. The software is also customizable for specific clients. With Frame’s conditional text, I can add all the information into one guide, say the administration guide. The government-contract-specific text gets marked with a conditional text marker. When I print, I can turn On the government text, or I can turn it OFF. I can make two versions of the manual from the same file with a couple of mouse clicks. The table of contents and cross references are all updated throughout the guide. I don’t have to maintain multiple guides for government versus private sector clients.

So, I had to go back to my manager and request the latest version of FrameMaker. I’d love to use InDesign, and I probably will use it for Quick Reference cards and other layout-intensive documents, but for my book-length documents, my documentation requirements are better met by Frame.

Yesterday I asked my manager if he thought they were going to approve the Frame upgrade. He told me that if I had requested it with my initial software list, it would likely have been approved.But since it wasn’t on the initial request, there was a chance I might not get it.

Lesson learned. The first of many, I’m sure. After all, I’m a lone writer, foraging my way through territory I’ve never visited.