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.