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.