creating a summary document with conditions

[ILWriter]

My company has a pretty long System Requirements document. We also publish a one-page summary of that System Requirements, with the most important information included. In my desire to single source as we are moving to Flare, I was hoping there would be a way to create an output that only included the information I wanted from the full document to the summary document automatically (thus only having to edit the information in one place.)

The problem with using conditions in this case is that I'd have to condition everything I DIDN'T want included in the one-page summary (which is practically the entire document). This seems unnecessary overhead to me. I haven't been able to find a way to have an "include" condition that includes ONLY what is marked as that condition and nothing else (including anything that doesn't have any condition on it at all.)

I realize that the above IS a solution, if nothing else, but I'm wondering if anybody has any ideas on how to accomplish this before I have to go and tag everything I want included in the main document.

Thanks!

[Msquared]

I have already raised a feature request for there to be an implicit condition of "Untagged" or similar, which would allow you to explicitly include/exclude everything that doesn't have any condition applied to it at all. That sounds like it would give you what you want. So perhaps you could join me in asking for this feature, and provide your specific example as to why you would like it. The more people that ask, and the more people that explain why it would be useful to them, the more likely it is that MadCap will understand the way some of us use Flare.

To your present problem. You may be able to do it with Advanced conditions, but I have to say that I tried using them to do something similar when they first came out. I couldn't understand how they were meant to work, and didn't manage to get the results I expected. This may have been that I didn't spend enough time to understand them properly - as always, real work gets in the way of experimenting with Flare. But in my defence, I have a degree in Mathematics and I was a software developer for nearly 25 years before becoming a technical writer, so unless you have a better degree than me, you may be bemused too . Unless anyone else can help here?

How I would do it is like this. I'd identify all the text that did need to be in your one-page summary, and put that in snippets. Use the snippet in the main topic where required. Then I would create a separate TOC for the Summary document, with separate topics. Each topic would contain any necessary headings, and one snippet. Your only problem now is remembering to maintain this system for future updates. So if you can implement it in a way where there is a one-to-one match between the summary topics and the main topics, I'd do that as then it will be easy to see if things are out of step.

If there will be a one-to-one correspondence between the main topics and the summary topics, I'd consider using a single TOC, with the main/summary topics interleaved, and each conditioned either MAIN_CONTENT or SUMMARY_CONTENT. Then, in the future, the pattern will be obvious - if someone adds or deletes a main topic, they will immediately see they need to add or delete a corresponding summary topic too.

[ChoccieMuffin]

How about creating snippets for the bits you will want in both places? To create your summary doc, add the snippets. To create the full doc, insert the snippets where they need to be. That way you only have to edit the snippets and not two files.

Does that work for you?

[Msquared]

That's exactly what I said @ChoccieMuffin - I just didn't get round to saying it until the third paragraph.

[ChoccieMuffin]

Sorry Marjorie, I posted before I'd finished reading.

[ILWriter]

@MSquared - Although I don't have your experience backing me in software (I'm pretty young), I do have a Master's degree in engineering... so I feel your pain when things don't seem as easy or natural as they should be . I'll definitely put in a feature request - I really just wanted to make sure that I wasn't missing something and that it didn't already exist. I feel like there could be a lot of uses for an "untagged" condition.

I couldn't really find a lot of information about Advanced Conditions, but what I did find made it seem like you couldn't do anything more with advanced conditions than you could with simple. Maybe I'll play around with that more today.

And as far as the snippet suggestion (thanks ChoccieMuffin for your weigh-in, a well), I figured that would be the only other way. I was hoping to avoid it because some of the summary vs. full items are certain rows of tables. However, I think I can rework the information in such a way to make the snippet suggestion work.

Thanks for the advice, and I'll just hope they listen to our feature request in the near future!

[Msquared]

You may have trouble creating snippets that include tables, although a snippet can include a complete table, you just can't create it directly for some reason. You will have to create the snippet, then add the table.

What you can't do, I'm afraid is create a snippet that just contains some rows from a table, then insert the snippet rows into an existing table. I've also raised a feature request to be allowed to do that.

if you do need a snippet that includes table rows, not the whole table, you could define a table style that has no space immediately before or after, and use that for the table in your snippet. So you are actually placing two separate tables, but touching each other so it looks like one table. However, if you do that, you will have to lose one of the good features of Flare, which is its ability to resize table columns to fit the content, because you won't be able to guarantee that the auto-sized columns will be the same for both tables. You can specify the column widths to ensure they are all the same. I couldn't in my scenario - I single source for Web and PDF and needed Flare to make its own decisions about column size depending on the output medium. So I ended up making snippets from the individual table cells and placing them as required.

[dorcutt]

Not to ask a really dumb question, but is it possible to make the whole System requirements document a single snippet, and place the same snippet in both topics? The big system requirement document would have to all be in one topic, but it would work, I think.

You would have to tag everything that ISN'T in the summary, but you could just condition out individual table rows like normal. Alternately, I suppose that you could tag everything as "System Requirements" (select all, one giant tag, set the color to white for sanity) and then tag the important bits "System Requirements Summary." You'd then make a target for the system requirement summary document, and set it to exclude the "System Requirements" tag but include the "System Requirement Summary" tag. The include would override the exclude, and you'd get the content you want with a minimum of fuss.

Would this work, or am I overlooking something obvious in my newbie-ness?

[ILWriter]

@Msquared: Yes I was noticing that - it really doesn't like snippets with half tables (I assumed as much). The problem is that I want to try and avoid complicated solutions - the writer maintaining this document is a very beginning Flare user and would probably get bogged down by complicated snippets. I'm starting to think that tagging everything might actually not be the worst idea.

@dorcutt: If I tagged everything, I wouldn't need to make the document a single snippet. Making the entire document a snippet wouldn't give me anything new - it would basically be like if it wasn't in a snippet. Additionally, having a 15-20 pg document be in one topic is bad for moving to web format, which as a writer I'm trying to get my company to move towards. However, for some reason, I never even though of making the condition tag white: talk about a huge increase in sanity! Thanks for that suggestion.

[dorcutt]

Excellent, thanks! I'm glad you got something out of me testing my knowledge anyway!