Slice Your Information Into Reasonable Chunks When Importing

[techwriter31]

When importing files from FrameMaker to Flare, you have to determine which styles are used to create new topics (within the "New Topic Styles" tab of the import file). So far when importing, I have specified that H1, H2, H3 (and sometimes H4, depending on the document) styles be used for new topic generation.

Within our Framemaker hardware manuals, we typically used H1 as a chapter title, immediately followed by an H2. So when importing, for each H1, I end up with a topic that only contains the H1 and no other content. This makes sense based on the import rules. So far, I've been manually copying and pasting the H1 from the single topic to the H2 topic that contains the introduction for the chapter and deleting the original topic that contained the H1. Is this the best method?

Also, is there a general rule of thumb on how to best "slice your information into reasonable chunks"?

[Beryl]

I'm facing the same issues. A manual I am importing has that h1-h2 issue in every chapter. (In fact it has a lot of h2-h3 stuff.) I have been promoting the h2 text directly following the h1 heading so that it doesn't sit alone. I remember my first editor (30 years ago!) drumming it into my head that every heading MUST HAVE text associated with it. Prescient.

As far as creating reasonable-sized chunks, I try to focus on the thought of a topic holding one major idea. In my case this is generally one window, one menu, or one task. It's a judgement call.

[LTinker68]

As far as creating reasonable-sized chunks, I try to focus on the thought of a topic holding one major idea. In my case this is generally one window, one menu, or one task. It's a judgement call.

Keep in mind that if you're single sourcing your project and producing online help, you don't want your topics to be too long because people hate having to do a lot of scrolling. So if I'm going to produce online and print output, I'll break the topics up more so users don't have to scroll as much in online output. In print output it doesn't matter how you break up the topics, because they'll flow one right after the other with the end of one topic and the beginning of another topic appearing on the same page, if desired.

[techwriter31]

Good point. I do plan to produce both print and online versions of these documents...which brings up another related issue. If the topics are too small, they seem strange when viewed from webhelp since you only see the single topic.

[LTinker68]

Depends on what you mean by small. If you have a bunch of short topics, then you could combine them into just two or three related topics, so long as the groupings make sense so the user can tell from the TOC entry which topic he/she wants to click on.

And for some content it makes sense to keep them short. For instance, if you're including a reference section of commands that can be used in your software, then each command could be its own topic, which gives you room to explain what the command is used for, the correct syntax for the command, and examples of variations in the syntax. You could have 50 commands that are all each short topics, but I would group related commands under books, so there could be 10 commands for configuring something in one book, 8 commands for retrieving information in another book, 12 commands for sending information in a third book, and so on.

Another recommendation for online output is to use togglers for things that take up a lot of room. For instance, I could have a 10-step process with some screenshots of key points in the process. I put each screenshot and caption into a toggler and add a link to the end of a step the user can click on to show the screenshot if he or she wants to see it. So when the user first opens the topic, they see the 10 steps without any pictures or captions. If the user wants to see a screenshot, he/she can click on a link to open the appropriate screenshot. If he/she wants to see all screenshots, I have another link at the top of the topic that says "View all screenshots", which displays all of the screenshots and captions at once. So when first opened, the topic fits in the screen easily. When all of the screenshots are shown, the topic flows down several "screens", but it's the user's choice to see the additional content.

[Beryl]

Depends on what you mean by small. If you have a bunch of short topics, then you could combine them into just two or three related topics, so long as the groupings make sense so the user can tell from the TOC entry which topic he/she wants to click on.

Do you ever find that you create online help that differs significantly in structure from the printed (or PDF) version? I mean do you find that you group information differently when it is broken into small topics?

[LTinker68]

It's more about the interactivity. For instance, in one project I had a process flow diagram that in online help had an image map and when the user clicked on a step in the process, a popup window appeared with a short explanation of that step. Each of those popups was a small topic, but I set those topics to not be searchable and they weren't in the TOC, so they could only be accessed via the image map. I didn't have to do a print output for that project, but if I did, all of those popups would have been short paragraphs after the graphic instead, since you can't do popups from a print output (obviously).

Another bit of interactivity is things like drop-down text, expanding text, togglers, etc. When building print output Flare will automatically expand the contents of those effects, but they can still look a bit odd in print output if you don't write or design them for both online and print output. And some effects it's just easier to have a topic that's for online output with fancier effects/appearance and another topic that's the same info but designed for print output.

Those are the types of things you have to think about. I've been bitten a couple of times because I designed something for online output only, then told months later that they want a print output, too, and I had to redo some things so that it would work in both outputs.