Single Source Diary - Day 1.5

I left off with: I next need to figure out the best way to add the Print Layout files to the project and define them.

Short and Sweet:
I can simply add these elements from existing Flare 4 templates to an existing (help-only) project, refine their design, and apply them (in a Print-Output target that I also have to create, later).

For Tech Writing Masochistics, the Excruciating Details:
In this project, almost all of the content is already in Flare. But there is no print target defined, and no definition of how printed pages should look.

Additionally, there is a chapter about hardware in the books that is not currently in the Flare project, because it was not part of the online Help. So that chapter needs to be imported.

Also, there are elements in the book, such as the print TOC, the title page and copyrights, and the preface, that are not in the Flare project yet. And another thing - the project Index is formatted for help, not print.

(I think I will set up the page formats first before I import these files.)

I think it makes the most sense to build the 'containers' for these objects in the project, and then either import them or recreate them. I think trying to import them to create the 'containers' would bring along baggage and would cause extra work in molding them to fit into Flare. But I will experiment with both approaches to make sure.

However, I also think that I can save some time by starting with the sample Print Output templates that Flare 4 includes. So if I create a new project, I should be able to put together a book template and then import it into the existing project. I hope. Back to reading about Page Layouts.

Well BZZZT! in a good way. It looks like it is just as easy to add the sample Page Layouts one by one to an existing Flare project, so there is no need to create a new one and copy stuff over.

I can add the following templates I need from the Project menu Add Page Layouts selection:
ChapterLetter.flpgl, FrontMatterResizable.flpgl, IndexResizable.flpgl, GlossaryResizable.flpgl. (.flpgl is the extension for Page Layout XML files.)

Next Steps:
I will need to figure out is how to use variables in the running headers and footers, but I am not worried as I saw steps on such things while skimming the Flare Printed Output Guide.

Discouraging Words:
I suppose this is my futile attempt to not appear to be a total Flare 4 suck-up.
But I did notice -
One thing that gives me slight pause - in the Flare PDFs available for download, the bookmarks are not perfect. There are some strays and repeats and out-of-orders, and a case or two where the subordinate levels don't exist. I don't know if this is a result of gremlins in their straight-to-PDF output or end of release frenzy by their Tech Pubs folks. Either way, it will be something to look out for. Given that we have similar problems with our Framemaker output to Acrobat sometimes (mostly unnested index entries and TOC entries in the Preface), I am neither shocked or chagrined.

Single Source Diary - Day 1

(After proposing a project to merge projects so that two books and two help systems can be produced using a single Flare 4 project, this is the morning of the first day. One other note: I am not posing as a Flare expert. Quite the opposite. I am intentionally stumbling through this the first time. It is up to the reader to decide if any foibles are mine or Madcap's.)

The introductory post of this series (Pilot Project with Flare 4) proposed some of the tasks that need to be defined and completed to create a single source project out of four (now separate) targets.

The next step I am going to take is to break down some of the objectives into tasks that need to be done.

What I am going to look at first is how the book templates we have in Framemaker should be implemented in Flare.

Short and Sweet:
I need to define Page Layouts in Flare 4 for each of the book components that are part of our Framemaker template.

Result:
I need four Page Layouts to implement the same structure as our seven Framemaker templates (I think). I don't need the Frame Book File because the Flare Project file acts in that capacity. It sounds like I can have one page layout that contains all the frontmatter (book title page, copyright/trademark page, TOC (a proxy - more about that in a later diary, I'll bet), and the Preface. I next need to figure out the best way to add these files to the project and define them.

Clarification (9/23/08): to be more specific, the four Page Layouts are: frontmatter, chapter, glossary, index. Our glossary looks different than the chapter, while chapter and appendix are almost identical. Preface can either be inside the frontmatter or a separate document using the chapter page layout.

Long-winded and Painful:
Right now we have seven template documents in Framemaker for Fontmatter, TOC, Preface, Chapter, Appendix, Index, and Glossary. One thing that seems evident to me is that in a Flare single source project, the structure will be similar, but I think I can combine the frontmatter, mostly because the TOC does not have to be a standalone generated file.

For example, instead of an independent file in the Framemaker book for the Frontmatter that is used as part boilerplate and part fill-in-the-blanks, there will be a frontmatter topic in the Flare project template that will serve the same role, but it will be a self-contained in the template. Well, I suppose it is still a file, but it is more tightly integrated into the project, as are all individual files in a Flare project. It will probably use snippets and variables in place of the master page boilerplate of the Frame frontmatter file.

That file can also contain the TOC and Preface, and use Roman numbering, if we decide to preserve that archaic convention. At least Michael Hughes considers it fairly useless in an online document, except to tell the reader "... if the page number is a Roman numeral, there is no useful content on that page."

The Chapter and Appendix have an almost identical template, except that the Chapter numbering differs. I will need to determine how number versus letter titles work in Flare (has not been an issue for Help) to determine if I need two topic templates or one.

The Answer: just one format I think because I can setup a chapter break that resets to 1 and changes numbering scheme to uppercase Alpha. (But I am not sure how that affects the page footers - so I may have to backpedal later.)

I do know that you can set up a first page that is always a right-side page for print output, but I do not know how you set up the topic that follows. I think that between chapter breaks (settings in your print TOC that signal a new chapter), the rest of the topics in the chapter just flow in, starting either as a new page or continuing an old one, depending upon their topic heading type.

This also bring up the hierarchy discrepancy we have between our help and books. In a book, we have a chapter title, and then Heading1,2,3 etc. In Help we have H1, H2, H3, but no concept of a chapter title.

Typically in our books the chapter title is in a larger font than the Heading1. This probably means that we will need to have a Chapter Title template topic that uses one tag for book and a different tag for help, conditionally, or perhaps that the Chapter Title template is used only in the book TOC. Typically our Chapter Title page has a small intro and a mini-toc for the chapter. Then often the first Heading1 is an overview, starting on the next page. In the Help we tend to just have the overview, without the short blurb and mini toc. We do often have a list of topic hyperlinks, but later in the topic. This may be worth re-examining.

I think at this point I am going to go off to look at the Flare 4 help and pdfs to understand how to do a mini toc in Flare, and to see if they have other advice on importing and setting up chapters and headings.

Back again...I skimmed through the section on mini toc that explains how proxies are used. So now I know what to use to create one. When I create a chapter title topic I will follow the steps to build in the mini toc proxy.

There is a section in the Flare Printed Output Guide that explains "Using TOC Depth For Heading Levels" in a printed TOC. This section explains how to use the outlin in your Print toc to build the toc in the target output. So essentially any topics that I identify in the print TOC as the Chapter Title topics will show up in the TOC that way, and in the correct order in the PDF.

There is also a section in the Flare book called "Specifying Chapter Breaks And Page Layouts" that explains how you let Flare know where chapters begin and end in the Print version.

Another important concept that comes up here is the difference between Page Layouts and Master Pages in Flare. In Flare, the newer concept of Page Layouts is best for print documents, while Master Pages are best for adding page-like elements to online content. For example, if you want to put a footer in your help with a 'breadcrumbs' trail to show how the topic links to higher level topics, you would put that in a master page. For now I think this project will be using Page Layouts, unless I can't make them work.

Even more Blather
One thing I have to add (writer compulsion is a terrible affliction) is that the objective of this exercise is not to find a way to consign Framemaker to the dustbin. It is more of a proof of concept for instances where there would be a potential benefit for single sourcing, and there is need of a help target. We have lots of hardware books and training books that do not have a help target, so any gain in single sourcing would be dissipated by the work needed to convert them.

Actually the training is potentially a third target for this project, but that would be excerpts, not single source. The training developers could use source from the project as a starting point for their training materials, but that would end up in Powerpoint and in Framemaker.

One other thing to mention is that my goal is not just to convert this particular project to single source, but to define a Flare project template that could be used to convert other projects. So I will build a project template, then test it out with this project, rather than build single sourcing into this project, then try to extract portions of it into a template.

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.