This feature baffled me for a brief time when I first started doing printed output (specifically to PDF) with MadCap Flare. I didn’t get it..and that annoyed me. But, eventually, I figured it out and it’s been a wonderful feature ever since. Let me show you how it works.
When building a help project, specifically adding a new topic, each new topic always starts with an H1. When you need to, you add H2s or H3s to each topic. In the end, each topic (or webpage) has a nice, neat information hierarchy established. This is because when reading help, the user generally doesn’t go through it linearly. They go straight to the pages they need. So it makes sense to start each page with an H1.
But printed output doesn’t really work that way, does it? Users tend to read printed documentation more linearly. The subject you’re looking for may be part of another section and we all know that not every topic starts on a new page.
So, a topic that starts with an H1 in webhelp may actually need to start with an H2 (or even H3 or H4) in printed. That’s where the TOC Depth for Heading Levels comes in.
That check box essentially lets you to start all topics with an H1 but allows those H1s to be different heading numbers for print. Strange concept, I know.
Here’s a TOC without the Using TOC Depth for Heading Levels check box selected. It’s not ideal and I can see a number of issues that need to be addressed – but let’s focus on the TOC headings only. Everything is on the same level and it’s hard to tell where certain topics fall in the information hierarchy. It’s jumbled, discombobulated.
Here’s how things look in the Flare TOC. While a hierarchy has been built in, each topic starts with an H1 so they will all be on the same level. This is not how we want things to look.
Here’s how we want things to look:
And when you select the Use TOC Depth for Heading Levels check box – that is what you will get. Meaning….the H1s for Features, New Features, and Uninstalling will actually be changed to H2s (and will look however you styled the H2s in your CSS).
And the H1s for Downloading, WS-FTP Pro, and Contacting will appear as H3s. And they will look however you styled the H3s in your CSS.
So, what happens exactly when you select Use TOC Depth for Heading Levels? Check it out. Here’s a screenshot of the same project, same TOC – all I did was select Use TOC Depth for Heading Levels.
Ahhhh…..I feel sooo much better now. I’ve gone to my happy place! What a wonderful hierarchy of information – and not just a jumble of topics on the page. The TOC in the PDF doc now looks like how it was built in Flare.
Try it – and let me know what you think about your results.
Special thanks to Ipswitch via MadCap Software for the sample project.
Hi,
This was great – thank you. I wonder if you could do a post on these two issues too.
A couple key concepts on how Flare deals with the TOCs. In the Print version, Flare uses the headings inside the topic to build your TOC and creates a new TOC from those headings – just like Word does it. Flare ignores any books or items in your built TOC.
So if you do want books in your Flare TOC to show up in the print TOC that are not linked to a topic, you must have Inject headings for unlinked books in TOC selected too.
Sue
Sue, thanks for the kind words. I can write a post on how Flare handles TOCs in both printed and online output.