Automatically generating a TOC based on a selection

[owilkes]

Hi All,

Maybe it's because I'm new to this, and don't understand the 'proper' way of arranging work, but it seems to me that Flare is missing something fairly fundamental (I would be delighted to be corrected on this).

We will be 'tagging' our documentation - at <p>, <div> and overall topic level - in a number of ways : Training text / training notes / User Guide / Implementaiton Guide for example, or 'End User' / 'Power User' / 'Implementor', or 'Internal Only' / 'Client' / 'Partner' etc.

Or 'Expired in this release' 'Expired in the previous release' 'Expired in the release before that'
Or 'Introduced in this release' 'Introduced in previous release' 'Introduced in the release before that'.

You get my drift.

So, I'd like to automatically generate training courses / user guides / output, where I state the rule "Give me everything relevant to End Users, in a Training Course, where it has not expired' - or 'Give me all Partner User Guides introduced in this release' it gives me all the topics in a TOC, which I then rearrange in some sensible order.

i.e quickly generate custom-made courses and guides, according to a selection.

But apart from running a bunch of searches, and then finding the topics that come out, and manually dragging them across - there is no way of doing this.

Is there?

I'm aware that you can set which parts make it through to output through the Conditional Text tab on the Target - but this would then imply dragging across the entire project into a TOC, much of which would not then be published - is this really the solution?

All suggestions appreciated, before I submit an enhancement request...

[lacastle]

Is this online or print output?

[owilkes]

It could be either, but will be predominantly online.

[NorthEast]

I'm not sure what you expect Flare to do; e.g. how have you 'tagged' your content, and how would Flare know what to do with this?

I'm pretty sure that Flare already has the tools to do what you want if you used conditions. When you're tagging the content, if you also mark it with conditions, then you'd be able to generate different outputs by excluding the appropriate condition.

And is there a problem if a large proportion of your project content might be excluded from an output? You'd have all the different content you might need in one project, and have the flexibility to deliver all the different combinations of content you might require for each output.

[owilkes]

Hi Dave,

I am putting conditions on the content - generally at the paragraph level, but also sometimes at the Topic level. I would then have to exclude everything that didn't fit that condition.

Presumably, I'd also need to put 'conditional text' on both the text within the topic, and also the topic overall with every condition used inside - otherwise, the topic is included, but blank. This makes for significantly more work.

Also, we only find out which topics are included after the ouput - which makes rearranging the order (through the TOC difficult)

A simple solution would be for the Search utility to involve tags, with include/exclude - and then these generate a TOC when that tag is encountered in the topic.

Or am I overcomplicating this? How would you select based on a couple of conditional text settings, to produce limited output? Is good practice to always conditional text the topics as well as the internal text?

thanks.

[LTinker68]

Is good practice to always conditional text the topics as well as the internal text?

You generally only need to a specific conditional tag at the level where it needs to do the exclude. That is, if you have a topic that's going to appear in every output but some of the content won't be used in a specific output, then you apply the conditional tag to the content inside the topic. If a topic is not going to appear in every output, then you apply the appropriate conditional tags to the topic itself to exclude it from those outputs. If a folder of topics won't be included in specific outputs, then you apply the appropriate conditional tags to the folder.

Depending on how many outputs you have, there may be multiple conditional tags applied at different levels. For instance, you could have content inside a topic that has the "TargetA" conditional tag (for example) applied, the topic itself could have the "TargetB" conditional tag, and the whole folder could have the "TargetC" and "onlineOnly" conditional tags applied to it.

And just an FYI with regards to the TOC... Online output will always include all topics in a project, regardless if they're in the TOC. They'll only be excluded if they have an exclude condition on them. Print output will only include the topics in the TOC. If you apply an exclude condition to a TOC entry, then in online output the topic will still be included, but its TOC entry will not (you only excluded the TOC entry). For print output, excluding a TOC entry means the topic itself and its TOC entry won't be in the output.

[owilkes]

Thanks all,

I was worried this would be the answer (secretly suspected, hoping to be shown some ingenious solution).

In truth, all our topics will be excluded at some point or another - so they will need to have conditional text set at the topic level if they have appropriate text in the topic itself. And as we are likely to have multiple different Conditional Text sets, it will be impossible to know before the content is entered what tagging should be done.

In a nutshell, I'm saying it would be useful to say 'if there is no valid text in this topic to be printed/built/generated, don't print/build/generate it - even if it hasn't been given the conditional text setup itself'.

Even with that, it would be even better if there was a 'toc builder' utility, which found all topics which had conditional text fitting the rules specified in a target, and built a new TOC with only these topics.

Strange, it seems like a fairly obvious tool - once I have single-sourced my documentation, and created the different conditions - building TOCs based on those conditions would be the next logical step, wouldn't it?

Thanks.

[lacastle]

Strange, it seems like a fairly obvious tool - once I have single-sourced my documentation, and created the different conditions - building TOCs based on those conditions would be the next logical step, wouldn't it?

Have you seen this functionality available in other software tools?

[i-tietz]

10 years ago I programmed and documented a content management system for websites - we had all sorts of automatisms like that.
If a CMS has the data stored in a database and not in files in a file structure you can program that sort of intelligence for building outputs. But for a bunch of files (like in Flare) that is hardly possible.
And software that is able to do that sort of thing is a lot more expensive than Flare ... talking about at least (!) 5-digit-amounts there.

[LTinker68]

Even with that, it would be even better if there was a 'toc builder' utility, which found all topics which had conditional text fitting the rules specified in a target, and built a new TOC with only these topics.

I could see something like that being beneficial for print output since only those items in the TOC are included in the output, but I don't know how helpful that would be for online output, which is more interactive and not necessarily designed to be read linearly.

[i-tietz]

Maybe merging projects helps?
You could have one project each for one of the sets, e.g. "Training text", "training notes", "User Guide", "Implementation Guide"
Then apply the others as conditions: 'End User', 'Power User', 'Implementor', 'Internal Only', 'Client', 'Partner'.

Then you wouldn't have all sorts of files in the same project. But you would have to think about what files are in what project thoroughly. You build helps and merge them together into one.

Maybe some of the "global project professionals" could help you here.


Alternative:
We do sth like that with Source Control (MS VSS 2005): We have all projects in the same VSS database which gives us the chance to link files into many projects. And but if one of those linked files is changed, every project notices and you can perform a "get latest version" in each of the projects. This is very comfortable, but I don't know whether other Source Control Software offers the same feature.

[owilkes]

Have you seen this functionality available in other software tools?

No - I admit I am new to this type of software, so probably bring a beginner's naivete with me.

If a CMS has the data stored in a database and not in files in a file structure you can program that sort of intelligence for building outputs. But for a bunch of files (like in Flare) that is hardly possible.

I thought the documentation in Flare is effectively 'data' - the location in the content explorer is not as important as the conditional text settings applied.

I could see something like that being beneficial for print output since only those items in the TOC are included in the output, but I don't know how helpful that would be for online output, which is more interactive and not necessarily designed to be read linearly.

You are right - it may well be more used for Print Output (ad-hoc training courses, high level training guides) - I understand items outside of the TOC are included for non-print based output. It is more a question of identifying the pages that will be produced, and arranging them as appropriate.

Maybe merging projects helps?
You could have one project each for one of the sets, e.g. "Training text", "training notes", "User Guide", "Implementation Guide"
Then apply the others as conditions: 'End User', 'Power User', 'Implementor', 'Internal Only', 'Client', 'Partner'.

The whole point of the project is to merge our current documentation into a single source! So we have one topic which has some info tagged as 'training', some as 'training notes' etc.

Anyway, thanks a lot for the suggestions - at least I know what can be done for planning and requesting enhancements.

[i-tietz]

So, I'd like to automatically generate training courses / user guides / output, where I state the rule "Give me everything relevant to End Users, in a Training Course, where it has not expired' - or 'Give me all Partner User Guides introduced in this release' it gives me all the topics in a TOC, which I then rearrange in some sensible order.

That is single-sourcing. You have one file which is in more than one project and if you change the file, it will be changed in all projetcs.

And what you wanted (s. above) means: You need an intersection of the sets "end user", "training course" and "not expired" (or "version 123"). This is nothing you can do in Flare, because with conditions the logic is "Include overrules exclude". E.g. if a topic or a folder has the condition "training course" it's in the help, even if texts or topics in that set also have the condition "user manual", which you want to be excluded. You cannot build using logical equations.

That's whay for real intersection of sets you have to go beyond conditions, i.e. different projects. And the wanted version you might get via versioning software like MS VSS.


Some more info about online help: If you have a topic in a TOC that is not part of the help because it has a condition which is excluded in the target, it's not in the TOC either.

[owilkes]

Thanks Inge,

We'll be using SubVersion as our version control for this - maybe we can use that for controlling the output. There's always a way, even if it is a messy one. At present, I'm thinking we'll have to search the html outside flare, do multiple filters on the output, and manually build our TOCs depending on what that tells us.

Will let Forum know what we end up doing, if we have success...

thanks.

[wbrisett]

Here's a radical idea... use a DITA.

You would have to write your topics as DITA topics, but you could also write a script that would allow you to read various attributes in the tags and generate as many DITAMAPs as you wanted. Then you could import those into Flare for the output. I do this on regular basis. I have a script that I wrote that will generate multiple maps depending on the settings I select. I then have multiple TOCs in Flare that I can quickly spin output from depending on the flavor of the day.

It might be worth a shot at least.

Wayne