Online topics flow together? Impossible?

[kmccall]

I'm creating an HTML5 help system for our application. Our app already has a crude help system - it's basically long lists of information that the user needs to scroll through, each huge topic is an aspx file requiring engineering intervention to update. So, I'm replacing it with a Flare system, that I control and update.

I'm firstly recreating what we have already using the topics from my user guide in Flare. BUT, the issue is my Flare topic are small and I basically need to recreate larger topics for the help system - exactly the opposite of what one would expect.

Sooo, I thought for sure I could just list the small topics in a Flare TOC and tell the HTML5 output to let them flow together as one topic just as they would if I created a PDF. But Flare tech support says this can't be done...?

This would seem like a basic fundamental necessity. When you're creating topics you'll likely have either too many, or two few, for different situations.

Surely I can't be the only person to need this, can I? Any ideas appreciated!

[techwriter31]

I ran into the same scenario when first converting to Flare, as we broke all of our longer topics up into smaller, modular topics for single-sourcing. Each topic has a single H1 heading and we can output to PDF or HTML5.

One method I've used is to insert a Mini-TOC proxy into the master page. While the topics still don't flow together, the Mini-TOC provides guidance as to what the user needs to read next. I think relationship tables could possibly be used for adding a list of "Related Topics", but I haven't used them for this purpose yet.

[kmccall]

Wow. Thanks! I think I can use that for at least some of my topics.

Thanks for the prompt response, too!!

[doc_guy]

If you store all your topics as snippets, then you can pull together as many snippets as you want into a single "topic".

So you have topics in your help system that match your current help system. Each topic calls multiple snippets, making individual topics as long as you need.

There isn't a quick way to do this to *all* existing topics already in your system, but you can go into each current topic and select everything and click the "Convert to Snippet" button.

Hope this helps.

[ksharkey9414]

Although I've had Flare for several years, I'm still a novice because I have had little time to get to know it. With that disclaimer out of the way, I'm going to tell you what I've been doing to get my online topics into a PDF-type flow. It's not pretty, and I'm sure that there's got to be a better way, which I'm hoping someone here can provide.

I, too, broke all of my FrameMaker topics into small modular ones when I imported them. This worked great, but when I tried to turn these little topics into chapter-sized flows for PDF, everything fell apart. So here's what I've done:

1. Started each chapter with the online help chapter topic.
2. Copied and pasted each little topic into this chapter topic.
3. Used condition tags (manual) for all but the original chapter topic piece.
4. Because all of the existing links point to the online help topics, I've had to change each one to point to the appropriate position in this new, all-in-one-piece chapter.

I'm still in the process of doing this, and I realize that now these topics are no longer single-sourced, and that when I eventually modify them, I'm going to have to replace the modified topics with new ones cut and pasted from my revised online topics. Have I gone insane, and there's an easier way to accomplish this, or do the Flare folks need to do something to make PDFs documents that we don't need to tear our hair out for?

[ChoccieMuffin]

Yes, there is a MUCH easier flow for you. I'll describe it briefly, and may well miss out steps (feel free to step in, anyone who spots a missing step!) but here's the general idea.

You don't need to do make any changes to your topics. Instead, you create a new TARGET for your PDF and modify the STYLESHEET (or medium) for the new target.

If appropriate you may even be able to use the same TOC as your help, if things are in the same order, even if there are some help-only topics in the TOC that you don't want in your PDF - you can do this using CONDITIONS.

Depending on how you have styled the first headings in your topics or how you have structured your TOC, you may be able to let the heading levels in your PDF be determined by the structure of your TOC. If your TOC is what you want to achieve in your PDF, open the PDF target and on the Advanced tab select the Use TOC depth for heading levels checkbox.

Think that should get you started, so STOP messing around with your content, you already have what you need!

[dorcutt]

Yes, generally speaking, whenever you find yourself systematically copying and pasting large amounts of content, you should stop and re-evaluate your methods. Flare is designed to prevent exactly that sort of situation, so there is almost always a better way. Posting on the forums is definitely a good way to get some tips if you're stumped.

[ksharkey9414]

Thanks for the advice, folks! I knew there had to be a better way. I do have some questions about your comments:

You don't need to do make any changes to your topics. Instead, you create a new TARGET for your PDF and modify the STYLESHEET (or medium) for the new target.

If by "create a new target" you mean under "Targets" add one for PDF, I did this, and I've been modifying my original (online) stylesheet using the print mode instead of online.

Depending on how you have styled the first headings in your topics or how you have structured your TOC, you may be able to let the heading levels in your PDF be determined by the structure of your TOC. If your TOC is what you want to achieve in your PDF, open the PDF target and on the Advanced tab select the Use TOC depth for heading levels checkbox.

I do have the "Use TOC depth for heading levels" checked, but my topics begin with a number of different heading levels--we're talking really small topics in a number of cases--in fact, most of the "headings" for these aren't really headings, they're just styles separating little topics ). The TOC depth is only three levels, so many of the small topics aren't included there. Does this mean that these topics won't be included in the PDF? It's quite possible that I may be totally misunderstanding what you're saying here.

Think that should get you started, so STOP messing around with your content, you already have what you need!

I know, I know--I should have asked for advice before I got this far into the process. Thank goodness I've done this on only one of the manuals!

[ChoccieMuffin]

For a PDF, the main purpose of the TOC is to determine the content of the end manual. To determine what appears on the Table of Contents page in the manual, you define the heading level of the appropriate style. Imagine this, where h1 - h3 have the attribute mc-heading-level set to 1 - 3 respectively.

Here's an example Flare TOC:

Front matter (Cover, copyright info etc - PRINT ONLY condition, as not needed for online help)
Chapter 1 (Level 1)
__Introduction (Level 2)
__Getting Started (Level 2)
____Installing (Level 3)
______Installing on Windows 7 (Level 4)
________Some other topic (Level 5)
________Another topic (Level 5)
________And another topic (Level 5)
______Installing on Windows 8 (Level 4)
____Logging on (Level 3)
____Etc (Level 3)
__Extra information (Level 2)
Chapter 2 (Level 1)
__Doing something (Level 2)
____Doing something special (Level 3)
______How to do another thing (Level 4)
__Doing something else (Level 2)
ETC...

In this structure the TOC goes down to level 5, but only the items shown at levels 1 - 3 appear in the PDF's TOC because of the mc-heading-level setting.

It doesn't actually matter what heading style the items at levels 1 - 3 have in the first line of the topic, when they are used in the PDF as described, they appear in the PDF using the correct formatting for h1 - h3 as defined in your Print medium, and the printed Table of Contents appears like this, without the blue items.

Front matter (Cover, copyright info etc - PRINT ONLY condition, as not needed for online help)
Chapter 1 (Level 1)
__Introduction (Level 2)
__Getting Started (Level 2)
____Installing (Level 3)
____Logging on (Level 3)
____Etc (Level 3)
__Extra information (Level 2)
Chapter 2 (Level 1)
__Doing something (Level 2)
____Doing something special (Level 3)
__Doing something else (Level 2)

Other topics that don't include h1 - h3, whatever their styles, still appear in the PDF but the titles don't appear in the table of contents.

As an aside, you mentioned that some of your topics don't even start with a heading. I wonder why. Do they actually need to be separate topics or should they be part of the parent topic? Or perhaps your "styles separating little topics" should be using a lower level heading rather than a <p> style? Just a thought, not something to worry about right now.

Did you generate your target? How did it look - anything like I described above?

[dorcutt]

To echo what Choccie says, I think that part of the issue is that you made your topics too granular. I did the same thing in some cases... it feels very "single-sourcy" to do during the conversion to Flare. Unfortunately, when using Web content, sometimes topics can ideed be too granular due to the way WebHelp works, as you discovered. This may require more of a manual fix than you'd like. I had to do the same thing, and despite what I had said earlier, it did involve a lot of systematic cutting and pasting.

What I did was I combined several smaller topics into bigger ones, with sub-headings for each of the old topics. However, this wasn't for a whole chapter, but rather for a small sub-section. Basically, generally speaking, the metric for how big each topic should be is "what would I like to see all together in one web-help page as a user." What techWriter said about using mini-tocs and related table links is also very important; this helps to you to keep topic sizes smaller sometimes. Also, what Choccie wrote about the TOC is absolutely spot-on. Your topics probably need to be bigger than they currently are, but nowhere near as big as a whole chapter.

For instance, my original Word document had a section in the Introduction chapter called "Overview of FictionSoft" with sub-headings like "What is FictionSoft", "The FictionSoft Process" and "The FictionSoftUI at a Glance." Originally, I made all of these topics, but when it came time to make Web output, it was clear that what I wanted was one bigger article called "Overview of FictionSoft." Each section was a paragraph or two, and was fairly meaningless on it's own, and even combined it was about a page or two of text.

To fix this, I copied each little topic's content into the bigger topic as a H2-5 or even as a p.SubHead or p.SmallSubhead style as the heading for each section. (Optionally, you can also save these smaller topics as Snippets for single-source reuse elsewhwere). I then carefully checked that each link to the outdated, smaller topic redirected to the new bigger topic, and then deleted the old smaller topic files.

Other parts of my Introduction chapter were not combined into this document. For instance, my "Key Concepts" and "Introductory Exercises" sections remained separate topics.

This is still a very manual process, and I only had to do it in a few places where it made sense. In other cases, I could keep the smaller topics and add mini-tocs and other links to make sure that they remained useful to a web-help user.

Hope this helps.

[ksharkey9414]

Again, thanks for the tips! I generated my target--with the cut & paste and links pointing to the topics within the chapter rather than to the separate topics in my content explorer. Which is not what you asked, but it did turn out beautifully. I'm going to try the new process on a different document, one that I haven't touched yet for PDF.

What I mean by small topics with no real headings is this: I'm documenting database software, and so I'm defining lists of keywords and qualifiers. The "heading" (styles separating little topics) I've used for these individual keywords/qualifiers I've called "Option." Some of the lists are short, and I can put them together in one topic. But some are very long, too long to have online folks scrolling through them all. With the longest list of these, I've included a table of links so they can go from the initial page directly to whichever definitions they want (many of these definitions are one sentence). I suppose that I could leave all of these definitions in one topic and consider the scrolling issue solved by this mini-toc. In fact, when I'm documenting the interface, I include the image (usually showing the relevant tab) and define all of the GUI items in one long topic.

There is one concern that I have, though: These topics will all be in the correct order, but when I say "flow," I mean no extra space between them. If each topic starts on a new page, however, then I'll need to continue my cutting & pasting, I guess. The first time I attempted to produce a PDF from this document, that is exactly what happened--I had many PDF pages, most with tiny topics on them and lots of white space. And they weren't connected--they were all in the PDF, but each had to be opened separately from the bookmarks.

[ChoccieMuffin]

Aha! That's an easy one to solve!

For the medium that you use for the PDF, you need to adjust the style of the heading that you're using so that the "page-break-before" attribute is set correctly. So the CSS for that style should include "page-break-before: avoid;" rather than no setting at all or "page-break-before: always;".

And there you have it - fixed.

Happy Tuesday!

[ksharkey9414]

My last, and biggest question, resolved! I couldn't have done it without you and dorcutt! Thanks so much for all your help

[ksharkey9414]

ChoccieMuffin and dorcutt: If only I had the info you gave me before I started PDFing that document, I would have saved hours and hours and hours. I just generated a PDF on a new doc, using your tips, and it looks wonderful! I don't have to cut and paste, I don't have to create new references to within the doc instead of to the individual topics, and I probably haven't yet discovered all of the other things I don't have to think about anymore.

If you're in the San Diego area, please let me take you both out to lunch!!!!

Karen

[ChoccieMuffin]

Hi Karen

If you're ever in the Surrey area of the UK, you can definitely take me out to lunch, but I think travelling to San Diego might make the "free lunch" rather pricey!

Very glad to help, and now you know that if you start doing a task that seems to be really long and tedious, ask a question before you go too far.

[ksharkey9414]

Hi ChoccieMuffin,

I've always wanted to visit Surrey

Karen