Single-sourcing TOCs for multiple targets

[CATERAF]

Hallo,

I currently have pdf and html5 versions of each user guide that we create.

I am wondering how many people keep their TOCs as separate for their different targets (e.g., 1 TOC for print target and 1 TOC for html5 target) versus those who have all topics in one TOC and condition them as print or html5. Currently I have them both separate because there are a lot of topics. However, I'm a little concerned that one of these days I'm going to miss a topic in one of the TOCs because they're separate. That said, I have a lot of topics in my TOCs (some of my user guides are long!) so conditioning them may leave me with a more messy TOC that I can't read well anyway.

What are your thoughts please? How do you do it?

Oh, also, for mine the structure of print and online user guides are different -- hence it's not as simple as just conditioning one set as online and the other as print. That's why I originally kept them in 2 separate TOCs.

Thanks,
Avril

[Nita Beck]

My usual response: "It all depends."

For some of my projects, I have a single TOC for the online Help and for the user guide, and use conditioning to keep online-only stuff (such as frequently asked questions) out of the user guide and to keep print-only stuff (such as title pages and topics dealing with software installation) out of the online Help. This works only because the online Help and the user guide follow the same general organization.

But for other projects, I have totally separate TOCs for the online Help and various print documents. For example, in one project, I don't produce a lengthy user guide but only a short quick start guide. In this case, the quick start guide has its own TOC. However, some of the quick start topics do show up in the online Help in a "Quick Start" book. And in that same project, I have a completely different print document that we call a "Feature Guide". My client decided years ago to dispense with the lengthy user guide and decided to go just with the quick start guide. But then they found that users needed a little more support for one particular gnarly feature that required a lot of explanation (and that they were getting a lot of tech support calls about), so for that I invented the "Feature Guide." It is an extraction of stuff from the online Help, but in a completely different arrangement from the Help. The tech support folks love it because they can email it to customers. (And it's also available directly from a menu in the product).

And then I have other projects in which the bigger-than-a-quick-start user guide has all of the conceptual and task material, but none of the field reference material, that being in the online Help. For those, I admit that sometimes I've used one TOC and sometimes I've used two, although I can't readily recall why I decided one way or the other.

Sounds to me like your decision to go with two TOCs is a good one, but yes it does put the burden on you to make sure that you don't miss something at times.

[CATERAF]

Thanks for such a quick response!

It has been working well so far keeping them separate but I do want to make sure I'm not missing things. I suppose even when I put them inside one TOC there's nothing to stop me missing it. The best solution is probably just to be thorough and methodical in my approach...

[Nita Beck]

Thanks for such a quick response!

You're welcome. I happen to be on the forums this evening answering what few questions I can. I've been pretty silent lately 'cause I'm stretched thin on several major "day" gigs ("day" being M-Su lately!).

The best solution is probably just to be thorough and methodical in my approach...

I absolutely adore Flare (despite its warts), but in my experience, it demands method and mindfulness, moreso than other tools I've used (and it's my third topic authoring tool).

[wclass]

My approach is similar to Nita's as well.

For most projects, the online help has a different structure than any related print output and so I have separate TOCs. Also, print output relies on the TOC for topic selection and for assigning chapter breaks, so my approach to those TOCs is a bit different. For large projects, I've gone a step further and created many separate TOCs for different functionality, and used drag and drop to include some TOCs inside others.

I have a checklist of things to do that includes "is it in all the right TOCs". I think it's better to make sure you have the right workflow rather than work with a dodgy structure.

For what it's worth, when we moved to Flare from the other authoring tool year's ago, one of the benefits was that fact that you could have more than one TOC!

[Msquared]

I single source one of my TOCs, where I produce a PDF document that mimics my WebHelp content.

I'm in the act of creating some content where the HTML TOCs are subsections of the PDF TOCs, so single-sourcing the whole TOC isn't appropriate. For this, I've created sub-TOCs for each chunk of content, then hooked them into the appropriate places in the TOCs for the HTML or PDF targets. That way if I make changes to one sub-TOC, I know the changes are reflected in all TOCs that use that sub-TOC.

Incidentally, this post http://forums.madcapsoftware.com/viewto ... 13&t=19115 contains a couple of ways of dealing with different print/web requirements for the book topics in your TOC. I think I like Paul Pehrson's solution better than mine, in fact.

[doc_guy]

I talked a bit about this at MadWorld 2014, but you do have the ability to nest TOCs together.

So, you could create a TOC for each chapter (let's say), and then you insert that chapter TOC into the "PDF BOOK" TOC, and then you also insert the chapter into the "ONLINE HTML" TOC.

That way, the chapter content is controlled from one location: the chapter TOC, but that chapter TOC is used in both the toc that is used for the PDF book, as well as the TOC that is used for the online HTML5 output.

Your PDF book TOC can then contain the frontmatter and backmatter topics. Your online TOC can include any online-specific topics (like "using this help system" or whatever). But you are still single-sourcing the individual chapters (or sections, or however you want to group them) in their own TOC.

It is beautiful, and it prevents exactly the trouble you're worried about: content becoming out of sync between the print and online outputs.

It is worth noting that in this scenario you have TOC's for the groups/chapters/whatever that aren't actually used by themselves in any target. But that is okay. They are nested into other TOCs instead. Remember with Flare 9+ you can also create folders in your Targets folder, so you can better organize the TOCs you create.

[CATERAF]

Thanks for all the responses! So much food for thought..

So, you could create a TOC for each chapter (let's say), and then you insert that chapter TOC into the "PDF BOOK" TOC, and then you also insert the chapter into the "ONLINE HTML" TOC.

That way, the chapter content is controlled from one location: the chapter TOC, but that chapter TOC is used in both the toc that is used for the PDF book, as well as the TOC that is used for the online HTML5 output.

I do like this idea but the problem is that for some html5 outputs I have chosen to remove all 'chapters' for the smaller user guides. I try to reduce the number of clicks required to get to the information the user needs so I take out the books where I can. Unfortunately this means removing chapter differentiation and often it's just a single list of topics that appears in the navigation menu. That said, it could be worth doing this for larger user guides which do have sections which repeat and then just not do it for the others..

I'm in the act of creating some content where the HTML TOCs are subsections of the PDF TOCs, so single-sourcing the whole TOC isn't appropriate. For this, I've created sub-TOCs for each chunk of content, then hooked them into the appropriate places in the TOCs for the HTML or PDF targets.

What do you mean by a sub-TOC please? I haven't heard the term before..

For most projects, the online help has a different structure than any related print output and so I have separate TOCs. Also, print output relies on the TOC for topic selection and for assigning chapter breaks, so my approach to those TOCs is a bit different. For large projects, I've gone a step further and created many separate TOCs for different functionality, and used drag and drop to include some TOCs inside others.

This seems to be similar to Paul Pehrson's solution but rather than chapters, it's functionality.. definite food for thought.

Thank you for all your responses!

[Msquared]

I made up the term "Sub-TOC". What I mean is a stand-alone TOC containing a subsection of your content, that could itself be linked into another TOC. It's not only topics that you can link into TOCs. You can also add other TOCs as linked items in a TOC. I wasn't aware of this when I set my very first Flare project up, whether because of lack of understanding on my part, or because the documentation and examples I had didn't make it clear, I can't remember now. But I may have considered it as an option then if I knew I could do it - so that's why I mentioned it.

This mechanism will allow you to single-source related chunks and reuse the chunks wherever you need them.

To do this, in the properties for that TOC entry, on the General tab, for the Link option, just choose Select TOC, rather than Select Topic.

But as wclass says, be aware that you set page, chapter and section breaks as properties on the topic entry in the TOC for your printed outputs. These properties are ignored for HTML outputs, but for clarity and control, I would only want to set these on items in the outermost level TOC. So for example, if you want to set a chapter break on a TOC entry (to restart section numbering), I would ensure that this topic was in the outermost level TOC, so that the "sub-TOCs" were truly reusable without having output-specific constraints.

[doc_guy]

This seems to be similar to Paul Pehrson's solution but rather than chapters, it's functionality.. definite food for thought.

Indeed, it is the same solution. I used the term "chapter" to refer to group of topics that should be seen in a certain order.

You could just as easily put all the topics that would be in a "chapter" in a TOC as flat files, no nesting. Then in your Printed toc, you insert an empty book for each chapter, and nest the "chapter" content inside that empty book. You'd then set your print settings/chapter settings/page layout settings in the empty topic.

In your online TOC, you'd just drop all the smaller TOCs together at the root level, and you'd get online output without any folder structure.

[CATERAF]

It's such a shame I didn't know this before using Flare. Still, better late than never!

Thanks to everyone for your tips and for sharing your knowledge

[doc_guy]

Glad we can impart some of our experience!

[Spectre]

Hi,

This is a question about multiple TOCs, but based on a subject matter condition, not print/HTML.

I have a couple of TOCs to create documentation that reflects the various versions of the product, with some topics being included in one TOC and excluded in another. I realise that this isn't strictly necessary and I can have one TOC with conditions set at the topic level. At the time I thought multiple TOCs might be simpler, but now I'm not so sure. However, I'm a bit surprised at the following behaviour:

If I apply a condition of VersionA to a topic in the Content Explorer, the square next to it appears in the colour I've assigned to the VersionA condition and that's fine, because I can clearly see that there is a topic that is right for one version and not another. But if I drag the topic into a "common" TOC, it loses that colour. I can re-add it by selecting the topic properties for the topic in the TOC, but the behaviour seems slightly odd to me. I'd have thought that you'd want the topic to retain the condition you assigned it in Content Explorer, when you drag it into a TOC. Any thoughts? I just want to check my basic understanding here.

Thanks.

[CATERAF]

I think the reason may be that the condition is applied to your topic located in the TOC rather than to the topic itself.
If the condition is applied to the topic (as opposed to the topic's listing in the TOC), the condition tag would be seen in the Content Explorer.
Since you've conditioned the TOC topic rather than the topic itself, the condition tag you see will only be with the TOC you conditioned it in, rather than in any TOC that the topic appears in.

Hope that makes sense (and is correct! I haven't got access to Flare to double-check at the moment).

[Spectre]

Thanks for the very quick reply. Just to confirm, I've placed a condition on the topic in Content Explorer, in Properties, so that my topic in Content Explorer has a coloured box next to it. But when I drag that topic into a TOC, the condition is lost, basically. The box is no longer coloured, and when I right click and select Properties, the condition has gone. As you say, when I condition the topic in the TOC, that same condition is not placed on the topic in the Content Explorer, and that's what I would expect to be the case. It's the other way round that I'm querying, Content Explorer to TOC.

Cheers.

[ChoccieMuffin]

If you apply a condition to a topic in a TOC, the condition only applies when that particular TOC is used, so you can include a topic in one TOC and condition it, and include the same topic in another TOC and not condition it. This can be useful if you use separate TOCs for your online help and your PDF, for example.

If you apply a condition to a topic in Content Explorer, that condition applies to the topic, wherever it is used. When you use that topic in a TOC, the condition is still applied. The coloured box in the UI is not necessary, as the condition is "stuck" to the topic, not just the TOCs in which it is used. So applying conditions in Content Explorer is "stronger" than applying the condition in a TOC.

For my own information, when I use a topic that I have conditioned in Content Explorer I like to add that conditioning in the TOC so I can see what's what, but it is not strictly necessary for the functionality. It can also trip you up if you do that and then change the condition of the topic later, because that change isn't carried across to the TOC, you have to apply it manually.

If you look at the html code behind a conditioned topic and a TOC in which you have applied a condition, it makes sense that the colouring isn't carried across from the Content Explorer into the TOC, but I agree it can be confusing.

[Spectre]

CM - thanks for the explanation. Cheers.