Any words of wisdom around a (first-time) multiple TOC?

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Any words of wisdom around a (first-time) multiple TOC?

Unread post by Dave Gehman »

Situation:
We're documenting software - let's call it KB - that has just undergone a major change to its user interface, along with some procedural changes. However, a number of users will continue to use the original edition, with the original UI and original procedures. (Why? In-process projects don't have the time to rewrite key things they've done to date).

It appears as though a second TOC is the way to handle "New KB" documentation -- just add new topics for new things and edit topics where details change. About a third to half of the original documentation doesn't involve the UI or new procedures and won't be changing.

I would think that a second TOC that's a copy of the first would be the way to begin.

However, the help file suggests that I, a first-time multiple TOC newbie, should NOT begin with a copy:

"Enter a descriptive title for the new TOC and choose whether you want it to be empty or a copy of the current TOC. If this is your first additional TOC you probably want it to be empty rather than a full copy of the entire TOC. Later you may want to make copies of existing additional TOCs that you then edit."

It doesn't explain why this suggestion is made... Tim, can you clarify?

I'd rather not spend hours copying 50+ topics from the original docs into the new TOC, when they'd already be there if I had just copied the current TOC.

Any sage advice on how best to proceed?
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Any words of wisdom around a (first-time) multiple TOC?

Unread post by Tim Green »

Hi Dave,

The suggestion in the help should probably be made a little clearer. It is actually perfectly fine to have a full copy of the original TOC, it would just be overkill if you actually wanted something with less content because then you would have to spend a lot of time deleting. 8)

One thing that is important is to understand the different behavior of the primary TOC (the original one) and any additional TOCs: The primary one should always be your "everything" TOC, the one that includes pretty much everything in your project. This is because it will include all the topics in your project by default, including those that don't have TOC entries, unless they are explicitly excluded with build options.

All secondary TOCs work the other way round: They include everything in the TOC, but by default only that. If the topics they include contain links to topics that don't have TOC entries in the current TOC you must do one of two things to prevent the links from being dead: Either a) Set the dead links option in View > Program Options > Compilers to silently include linked topics, or b) Use explicit include options to include the target files. This is important, because when a secondary TOC excludes topics that are linked to you don't get a compiler report message telling you that the target of a link is not there.

Using the silently include option (a) is the easiest, but it also needs to be used with caution. Once it is on it will silently include all topics linked to that are actually excluded in the current build/TOC. If you have forgotten about links to things that you actually absolutely don't want to have in your current build it can be a problem. As always, you need to weigh the pros and cons of the different methods for doing things. :?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Any words of wisdom around a (first-time) multiple TOC?

Unread post by Dave Gehman »

Tim Green wrote: It is actually perfectly fine to have a full copy of the original TOC, it would just be overkill if you actually wanted something with less content because then you would have to spend a lot of time deleting. 8)
Ah, I see - in this case, the material under the second TOC has more info, not less.

The more I think about it, simply cloning the original file might be the best tactic. The original will be going away altogether in a few months. The main structure of the help file remains the same -- the changes result in many new features, enhanced features carried over to the new version, and some changed basic procedural things.

If anyone has insights into why a simple cloning wouldn't be the right solution, chime in. I can't see any down side to that tactic.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Any words of wisdom around a (first-time) multiple TOC?

Unread post by Tim Green »

Dave Gehman wrote:Ah, I see - in this case, the material under the second TOC has more info, not less.
Then it's better to do it the other way round: Make a clone of your current TOC and use that for the version with fewer topics. Then add all the additional topics to the main TOC.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply