Conditional Text Zombies

Funny little story about a bullet in the last post. I worked for a company a while back that was a spin-off of a spin-off, where some tech pubs department members migrated from the mother ship to a seedling, then to another seedling when the options dried up at the first. Being loathe to throw anything out or to re-invent the wheel, these intrepid explorers loaded the first company's Framemaker files onto the covered wagon and brought them to the first spin-off, making enough cosmetic changes so it didn't look like a rip-off, but preserving the basic structure of the book. When some of the pilgrims moved on to the next colony, they loaded up the new files, brought them to the new promised land, and jimmied them up a little to look different. In both cases, this consisted mostly of changing the font and colors of the headings and table/figure captions, using a different look on the cover page, and substituting new graphics for the company imprints.

Well, by the time I got to the third company, as a wage slave rather than a stakeholder, they had published a release or two of most books. It was a hectic environment, and on one document, they had a publishing mistake - a book went out with what looked like some extraneous pages in a couple of places, almost like the old days when you picked up a job at a printer and found someone else's email interleaved with your manual's chapters. People thought it was a fluke because the Frame source looked just fine. Then it happened again, fortunately on a review draft.

Everyone was mystified. So they asked me to look at the document. Honestly I am less of a Frame guru than I should be, but I am a decent detective. It turns out there was conditional text buried in the document, not from the current company, but from both previous companies! One chunk was a fairly extensive two page blurb about the original company, including graphics and logos and all sorts of incriminating stuff. But mixed throughout was sniglets of stuff just waiting to be accidentally exposed.

Essentially, the writers who spread this disease had taken a book from the first company, used it as the basis of multiple books for the second company, and then taken one of those books to the third company to use as a basis for other books. So what we really had was a book masquerading as a set of templates, where only the text had been cleaned out, but the reference pages, master pages, and wells of conditional content still remained, at least in part, from two prior companies, each of whom, by the by, were competitors of the current place.

The current writer had tried to conditionalize some text for our current company, and in doing so had called back from the nether regions a bunch of this stuff from beyond the grave. It was like the tech pubs version of a zombie movie.

If I remember correctly, much of the conditional text from company 1 was all blue, and that from company 2 was all red, so that when you exposed both, there were globs of color clumped into various places in a given chapter. And because text copying and movement had inadvertently carried conditional stuff along with it, there were multiple instances in some cases.

So the department manager sent me on a stealthy search and destroy mission to find and terminate any instances of undead conditional text in the templates and in the books created from them. I was Van Helsing for a week (yes, I know, he hunted vampires, not zombies; perfect analogies are just so prissy; I prefer a touch of dissonance, some grating and grinding). When I finished, needless to say this was not a widely discussed success story.

I am sure the passage of years has inflated and distorted some aspects of this, but it kind of sums up my feelings about conditional text. I will end with another tortured analogy, quoting one of my favorite movie lines, to sum up my past feelings about conditional text. In Snatch, when cousin Avi (Dennis Farina) returns from England, US Customs asks him "Do you have anything to declare?" He replies "Yeah. Don't go to England."

Pilot Project with Flare 4

After going over some of the tutorial 'movies' on single sourcing and other topics, I have decided that I am going to use an upcoming project as a pilot for single sourcing with Flare 4.

Since I have this blog space, I am going to use it as an excuse to keep somewhat of a record of how the single-source project proceeds, airing the successes, false starts, stumbling blocks, and eurekas as I muddle through the process of learning how to use Flare to tame this project, and also to provide a test case for single sourcing other projects of mine and of the writing group.

Trying to put on a positive spin, I will describe my working process as spontaneous. What that really means, though, is that I typically leave a minimum footprint for a project record. Great for ecology but not so good for repeatable processes. So by logging what I am doing here, I hope to be able to better assess, analyze, and standardize what I have done, if I can successfully complete the project as intended. If I cannot, I will be better able to determine where I messed up and how to correct it.

Here is a description of the task as I see it. We have a product that allows customers to create badge layouts for access cards they issue to employees and visitors and contractors. The access cards are typically proximity or magnetic (swipe) cards that unlock building doors or provide other access (elevators, parking lots, etc). This product has two versions. One on our legacy access control system, the other on our new .net platform. Both products use the same base code, but differ slightly in features and in the way they work with the platform (the new platform stores stuff in SQL, the old one in separate files).

So while there are differences, it is fundamentally the same product. The next release of both versions continues the process plan by Engineering to merge the feature set so that both platforms support the same version, and a more dynamic interchange between them is offered to customers who have both our platforms.

Presently each product has its own help system and book. These have very similar content, as my authoring has been topic-based, with topics lumped to make book chapters. But essentially there are 4 project sources. Using Flare, I want to attempt to reduce this to one source set.
I do expect that I will still need to produce 4 outputs as before.

Here is an outline of the basic tasks I think I need to perform to do this. I am not numbering these yet, though I do have an inkling of the order they will require.

• The help for both is already in Flare 3.1, but in separate projects.
• We do not yet have a print media definition in Flare, so we need one.
• Both books are in Framemaker using our well-defined book templates.
• Those templates and their features need to be built into the print media definition.
• The help systems are almost identical in look and feel, with the exception of product logo banners. A previous blog entry covers my solution to that issue. (Flare CSS...)
  
• The books currently have a hardware related chapter that is not part of the help.
• The version for the newer platform does not yet support a major feature that is in the legacy product.
  
• The help/chapter for that feature is written and will need to be conditionalized for the newer platform. It is an 80-page honker.
  
• It is possible that some aspects of the feature will be implemented differently, and will support different card technologies, readers, and printers than the older platform.
• I want the books produced by Flare output to be virtually indistinguishable (by me at least) from the Framemaker version. Reasonable compromises will be made I am sure. but if it looks that close, no one else outside of the writer's colony will have a clue.
• I have little experience with conditional text, except for the experience of cleaning up after a bad implementation at a previous job. So setting up conditions for both print vs help and for feature inclusion/exclusion will be challenging (at least to do it right so that it is sustainable and not a confusing mess.
• Right now, the project time lines for either project are not set except as vague fiscal quarters, so I am not sure which version comes first.
• I have to create 4 TOCs for this; 2 book, 2 help. Contents will be fairly close, but the books have a preface that is not in the help, and a copyright/trademarks page.
• Typically we put far fewer screen shots in our help, assuming the customer is staring at the screen we are talking about. But I have to say that looking at Flare's own help, they tend to throw in quite a few screen shots and they have no compulsion against making them enormous. So I am going to think about balancing the help real estate vs the degree of difficulty incorporating the book's screenshots into the help (all those captions and cross references are gunky).
  
• After I have set up the book template aspects of this, I need to import the hardware chapter and put it in the book side TOC.

This list hopefully covers most of the big ticket items that need to be done to plan the project. When I get back to the salt mine on Monday I will probably try to refine this list and put it in some semblance of order, and reflect on what I have forgotten to include.

Day 1 with Flare 4

I installed Flare 4 today and started playing around.

Things that I liked right away (disclaimer - these are in no way important, just stuff I liked):

• File> Zip - you can make a zip file of your project right from the file menu. Very handy.
• Footer in the help listing all the PDFs you can download from Madcap. Some very useful titles. If you are going to have a 7 line corporate address in the footer, you might as well do something useful at the left margin.
• Select table cells, right click and viola! Cell Content Style menu selection - you can assign a style to multiple table cells. Good Glory!
• The new printed output tools (Blaze inside) look good, and the interface is modern and clean. What Frame could be if Adobe hadn't neglected it for years (still love ya Frame, but I loved my 82 Chevy Nova too).
• Review toolbar and X-Edit built-in. Not sure how Engineering will take to it. Maybe if I say XML repeatedly they will be interested.
• Layout Dropdown - you can edit in a web layout or a print layout. Maybe some of my compadres will author more Flare First (rest of the group is book first help later; I am the opposite. If I wanted to write chapters, I'd be channeling Normal Mailer rather than [insert rich and famous web author here].
• Font Properties button - Ok, it was there before. I am such a dedicated CSS-er that I never ever opened it to inline font properties, and saw that the example text was "The cute red cat in the hat"
• Global Project Linking - This is one thing I am itching to try. We have the same stylesheet copied into over 40 projects, but god knows what has happened to them over the past several releases. They have probably been tinkered (I know I have changed things in one and not the others).
• Video Tutorial on single sourcing in Flare. I will be watching this one in the morning.
• Widow and Orphan Control - I just had to say that this always reminds me of some horror movie where single moms and abandoned children are turned into zombie slaves by a publisher.
• Basic Madcap Analyzer inside - because my guess is that I could never get my boss to spring for the full product, at least I get some reports with V4.
  

The bad news is I have not found anything to complain about, so I guess I will have to go home and mock the cat to bleed off some aggression. He doesn't like it when I imitate him, but he puts up with it because I am the one who wields the food scoop.

There are scads of things that I haven't even looked at yet. This is obviously an incomplete and seriously quirky list, and not in anyway an attempt to review the product.

But I hope it was interesting anyway.

Reviving Oblivion

This blog has so far suffered from all work no play. That is hardly reflective of my real life. So let's talk about about Oblivion. This game is Bethesda Softworks to a T - monumental, beautiful, engaging, virtually limitless in depth, and a crash king. It is so Bethesda that even the console versions crash with regularity. The last official patch was ages ago (well, 4/30/07, ancient history for a PC game).

Fortunately some dedicated folks (Quarn & Kivan) have put together the UOP - the Unofficial Oblivion Patch. If you have played Oblivion on the PC, you will be more than amazed at the way crashes are minimized. I have now played days without crashing during the game. Admittedly, the game crashes to desktop on exit on my PC almost every time, but it never freezes the whole system like it used to. What amazes me most is that you can open and play games that were saved on pre-UOP versions of Oblivion - lots of times big patches are not backward compatible.

If you have played Oblivion before and took it out of your rotation because of the crashes, you should download this patch and give it another try. You can get the patch at (among other places) PlanetElderScrolls.

Have fun. Meanwhile, I'm heading back to my house on the waterfront to soultrap conjured creatures and recharge my Shadowhunt bow.

Flare CSS Management (and a neat little trick)

We have two main products, each with a main help system and one or more smaller surrogate help systems. One main help system is a master with around 30 merged .chms. The other is one big chmglob with just as much info, but linked to a legacy product that would not know how to point to merged chms, so say the Engineers.

If you know help, you can infer from this why I have a concern about managing CSS formats.

The legacy help system was converted from RH, and brought along untold amounts of format baggage in the guise of inline formatting and residual crap. We cleaned all that up, gave it a clean and fresh look (clean white vs unbrushed teeth yellow background).

We then started fresh in Flare on the new help system for the newer system. The newer product is .net, C#, VS2005 look-and-feel, which is ultra modern compared to the older. But the customer base is very much the same, so we adapted a very similar look and feel for both help systems.

So we used the same CSS formats for both help systems. Only difference was the banner on every topic.

Topic Banner for the new product



Topic Banner for the older product



Over the course of like 4 releases of each product, with around 40 .chms, and with us adjusting to the Flare way rather than the RH way, variances have crept into the many copies of the CSS in use.
Typically, when a new format was needed to handle a quirk or something we had overlooked (for example, text in tables that looked OK in RH seemed to be rubbing shoulders with table borders in Flare), the change got made by a writer and did not get propagated to every project. I am sure you can see where this got us.

So now that the hubbub from the latest releases has subsided, and we are about to load up Flare 4, I am spending some time looking at these CSS issues to both repair the CSS and plan ahead.

What Flare 4 appears to give us is a way to globally manage our CSS - Global Project Linking. If I read correctly what has been announced, we can put our 'master' CSS file out on our shared network drive and have all the Flare projects link to it. My guess is that we can lock it and thereby centralize changes, so that we don't end up with 40 different variants.

Of course, to do that, we need to have one CSS file to rule them all.

That brings me to The Neat Little Trick Part in the title.

By using the Stylesheet Medium setting in Flare's CSS Editor, I can set up, in one CSS file, two versions of the topic background, each of which uses a product-specific banner. Medium is most commonly used to distinguish between print and non-print formatting in a Flare target, but in this case I am using it to distinguish between two variants of online help.

Stylesheets Mediums are described well in the Flare Help (topics = Creating Medium Types and Associating a Medium Type with a Target), but the focus is on print vs non-print. This is another way to take advantage of this feature.

One other note - projects for help system A will have only the target for A, and projects for Help system B will have only the target for B, to avoid unfortunate results (product A has help banner for product B).

Madcap announced Flare 4

Madcap announced Flare 4 yesterday, and we received email that we can download it now (we have a maintenance plan that includes upgrades). I am eagerly anticipating trying the released version, after fiddling around with the beta for a while. But I also realize there is a lot of work ahead if we are to get everything out of it. I am responsible for our formats and templates, and with a new release invariably there are changes.

In addition, Flare 4 includes the capability to go to print from a single source, but the catch is that you have to add a design for your output for print medium, or in our case, re-implement our Framemaker based design. or however close we can get to it.

My first step is going to be to visit the Flare forums to see what the early buzz is.
After that I will download the Flare 4 software and install and register.
Then test drive it for a couple of days.
Then have one of the other writers guinea pig install it on their system.
Then one by one work with the other writers to install on theirs.
Meanwhile I will be testing out how our current CSS performs with Flare 4, and looking to make some minor changes.

One great thing about Flare is that you can have multiple versions existing on your PC at the same time, so there is much less risk that an upgrade will mess up existing projects, or if the upgrade has key defects, make it impossible for you to produce output. I have had other situations with other company's products where you must de-install the previous version to install the update, which then doesn't work right. Then just try to re-install the old version, along with patches you don't remember installing, only to be told that some registry setting prevents the installations, sorry. What a nightmare that can be.

Working with Flare is not all rum-cake and spiced cider in front of a toasty fire, though. There is no doubt that editing XML files in Flare exposes you to more clunkiness and requires more format thinking than writing in Word or Frame. The good news is that you can use the structures to advantage; the bad news is that you have difficulty avoiding some deep delving to understand why things don't look as you wish.

This is especially the case with older project converted. Flare tries hard to cleanup up residual garbage when converting, and does an admirable though not perfect job. But you will still trip over instances where someone did something tricky in a previous revision in a previous HATT that either conflicts with the XML way, or no longer has the same effect. Sometimes these effects are invisible in the XML editor but very visible in the compiled help. Then you just have to open the internal text viewer and look at the code, and hope you don't delete anything crucial.

But that is with 3.1 and prior versions. I am sure that with Flare 4 it will be church bells and the choir invisibule singing Hallelujah all day long.

Meanwhile in the workplace

We are awaiting the release of Flare 4. I tried the beta and it was pretty good, but then my PC got crabbed up and we had to give it a wipe, so bye-bye Flare beta. Did not reload it because by that time we were under the gun to release product, so no play time.

Now the release is just about out, so it would be a good time to do some more preparation. We are ready to upgrade Framemaker and Acrobat to 8 (yes we lag a good bit; but if we upgrade and hit a bug that stops our production, we are hosed so better safe.

Between releases, I am looking at making changes to our Frame templates, and to go back through our Flare help and update the css files (in the rush, they tend to get out of synch). Also looking at aligning the Frame template formats closer to the Flare css formats. The books are Book Antiqua while the Help is Verdana, and we do move info between them so it would help to reduce retagging.

It is nice to dream about single sourcing in Flare (or Frame if it actually worked well, but) and also about moving to DITA, but in our undermanned situation, the conversion would bog us way down. So small steps is the best way we can make progress.

Boy this is boring stuff for anyone reading from the outside. But it is good to record it in frozen electrons, rather than mentally rehash it on a daily basis.

Get this started

Anyone who claims to be a writer has to have a blog, right?

I have been a writer in hi-tech for over 20 years, but I have been resistant to blogging. Lately however I have found some very interesting blogs by other tech writers and by people at tech companies. Also, the company I work for is thinking about starting a dev blog, which I might have an opportunity to help with. So I might as well get some practice in.

I am a technical writer at Software House, a company in Lexington, MA. Software House makes security products (hardware and software access control systems).

I am also a hockey and soccer fan, an online gamer, a father, a diabetic, a New Englander at heart, a centrist liberal independent, a lapsed Catholic, a heart patient, an Irish-American, Providence College grad and a curmudgeon. I like Guiness, jalepenos, the Boston Bruins and most other Boston teams, the Friars, the Grateful Dead, DKM, mythology, military history, movies, Chourico, wargames, and RPGs. I am also an old coot. I turned 55 this year.

I am undecided about the presidential election, with one exception. I am sick to death of both party's and pundit's attempts to slander every candidate, shamelessly.

I am anxiously awaiting the start of the hockey season, and I am today aghast to learn that my greatest fears for the New England Patriots seem to have come true. Reports are that Tom Brady might be out for the season after being injured in Game 1 of the NFL season. Yikes.