MadCap Software Forums

Hi,

I want to give a try to the following project. There's a complete document that contains numerous sections. There is a subdocument that contains a few of those sections. I want to author my content only once. Each section contains several procedures with supporting images.

What are the best practices for me to set up my Flare 12 project so that I can create one document with all the sections and a second document with only a few of the sections.

Assume PDF output for both.

Thoughts?

Cheers,

Sean

For example, do I do this by manipulating tables of content?

Such as, I create one toc for the larger document and one toc for the smaller document? Output the larger toc to PDF for that entire content, and output the smaller toc to PDF for the subdocument?

That seems to be what I should try. I don't fancy using conditions for this.

Sean

Hi Sean.

There is no one-size-fits-all best practice. But your proposed solution should work just fine. Other authors might have a single TOC and then condition it somehow to keep things out of the short document. But there is no rule that says that you can’t have two TOCs, one for the full doc and the other for the short doc, as you describe. If that seems easier and more intuitive, go for it. It also might be more fail-safe. You won’t run the risk of forgetting to condition a TOC entry and then have it show up in the short doc. (FWIW, I use multiple TOCs for different PDF outputs, instead of one giant, condition-laden TOC.)

Thanks.

So, what you are saying, is that some people might use one toc and use a condition for each of the separate sub documents it spawns? I might try that, but my approach seems more ... clear.

Cheers,

Sean

Clarity matters. Simplicity is important. My philosophy as a Flare designer is to always seek the simplest solution, the clearest solution, as that will be easiest for anyone who follows me to maintain the projects I design.

I've managed a couple of large projects using conditions. As Nita mentioned, it can get cumbersome. But project also had conditional text within topics for the different outputs/product versions, so the multi-TOC didn't really work for me.

If you can tailor your TOCs and then use the do not link un-referenced files setting to exclude the rest, you're golden.

trent the thief wrote:...and then use the do not link un-referenced files setting to exclude the rest, you're golden.

Our friend is building PDFs, so the “do not link in-referenced files setting” (aka “Exclude content not directly or indirectly linked to the target”) isn’t applicable.

I'm doing something similar... and I just want to run it past people with more experience before I get too far into it all.

I have:

• One large Flare project (only just migrating, so not that large yet)
• So far, 3 PDF outputs (different products) and 3 HTML outputs (for each of the products) - HTML is just the individual topics... I'm building a web output but the developers only use the individual pages linked directly to individual pages in the product and the rest is ignored. (As an aside, I was hoping to share topics across the help and the PDF, but so far haven't worked out how. It's not a technical issue - it's more that I have fixed size to play with on the web pages before it becomes unwieldy for the user because of how they are linked and the fixed window.)

The release engineer likes to take the source and build the PDFs himself (to check it's all working, I think )
When I'm not around (I'm freelance, and this is only one of many clients) the developers want to be able to make minor corrections themselves.

So, my plan is:

• Have one target per output
• Have one ToC per output

Because the developers won't be familiar with the Flare project setup, I'm thinking of telling them to open the correct ToC and then open the file they want to edit from that... that way, they won't inadvertently open a topic that contains similar information but is for a different product. It also means that as their starting point will be the previously created PDF, they will find what they want relatively easily. Building the targets is then very straightforward.

So far about 95% of the topics are common to all outputs, but that will reduce (it just happens to be that the first three products were based on each other - there are currently 8 active products that can be categorised into 3 product types, and I've just done one type). Of those 95%, about 10% contain conditioned paragraphs... slight variations in instructions. All other differences are sorted using variables, which are defined in the targets, as are the conditions.

This means:
1 - I don't have to tag the ToC itself. It makes it easier for the developers to navigate...if it's in the ToC, it's in the PDF, and in that order.
2 - I don't have to worry about correctly tagging topics to exclude (and more importantly, neither does anyone else... if they aren't in the ToC, they don't get built).

My question... Am I missing something fundamental here? Am I setting myself up to fail? (I may end up with 20-odd targets, but I doubt it will ever get to more than that. I've been involved with this company for nearly 20 years, and they've always had around 10 active products maximum.)

The one thing you'll get yourself into is if you add core functionality that requires new topics in shared material that spans across all products, you'll have to edit all the TOCs to include the new topic. Given your other concerns, and especially if this is considered unlikely, then you may accept the risk/work required is less pain than the alternatives.

Thank you. I'm fairly relaxed about that... Adding a topic or two to two or three To six seems a small price to pay. Alison

You can also include tocs within other tocs - I find this useful for modules that are shared across different products. This is good for when I'm updating documentation for that module and I need to add the changes to all the supertocs.

I didn't know you could do that... absolutely brilliant!
Thanks a bunch... Alison

If you are building html output, you can configure how the subtoc is merged when the output is built. The options are on the Advanced tab of the subtoc properties. I usually choose to replace the node with the merged toc.