Conditional Text or Separate Topics?

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Post Reply
ericspiel
Posts: 28
Joined: Tue Aug 30, 2005 3:14 pm
Location: Oxfordshire, England

Conditional Text or Separate Topics?

Unread post by ericspiel »

Hi all,

I hope I've put this in the appropriate forum, so do feel free to move it if it fits in better on another one.

This is a somewhat general question soliciting advice on structuring a help project. Our software has two personalities, one for each type of client (sales house or agency). Thus I have created two Custom Builds ready for use. The content for each personality is 95% identical but there are a handful of dialogs and windows which have slightly different buttons/menus/appearances etc.

My question is, do you think it better to have:

1) For each applicable topic, have two sections, each of which is surrounded with Condtional Text directing it to the relevant build, or

2) Two separate topics to contain the information and use the Builds which include this topic: checkboxes in the Topic Options tab to control the output. I would want to use identical topic names in the TOC and manually select sensible names for the Topic IDs.

Any additional file size would not be an issue. I'm just trying to think down the road which method will be better to use when it comes to making amendments.

All comments or suggestions are most appreciated and welcomed.

Eric
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi Eric,

How you do this really depends on how much common text you have in the two topics involved. If they share a lot of text it will generally be more practical to use one topic and conditional text. If they are very different it is generally easier to split it up into two topics.

If you use two separate topics you should consider using embedded topics for the text that is the same in both versions. This will enable you to avoid having two different copies of the identical text. When creating the "source topics" for your embedded topics always remember to disable all the "Builds which include this topics" options in the source topic's Topic Options -- otherwise a copy of it will be included invisibly in HTML Help and can be found by the user with Search.

See the help for more details on working with embedded topics.
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.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Unread post by Martin Wynne »

Hi Tim,
Tim Green wrote:When creating the "source topics" for your embedded topics always remember to disable all the "Builds which include this topics" options in the source topic's Topic Options -- otherwise a copy of it will be included invisibly in HTML Help and can be found by the user with Search.
Isn't it always better to use an Invisible Topic for such embedded topic chunks? Is it still then necessary to de-select the All Builds option?

Martin.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Martin,
Isn't it always better to use an Invisible Topic for such embedded topic chunks?
Yes, that's a standard part of using embedded topics, as described in the help. The only time you would embed a topic from the TOC would be if you also want to have it accessibel directly at one point in the TOC -- there's nothing at all wrong with that, if that's what you need
Is it still then necessary to de-select the All Builds option?
Yes, absolutely, always. As explained in the help, the invisible topics are only needed to "source" the embedded text at compile time -- H&M just reads a copy. If you don't exclude them they will be included as invisible topics and can be found with Search, which can be confusing the for the user and inflates the size of your file a little (just by the size of the text).
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.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Unread post by Martin Wynne »

Hi Tim,
If you don't exclude them they will be included as invisible topics and can be found with Search
This surprises me. I have been using embedded invisible topics a lot. I have not de-selected All Builds on them, but the invisible topics are not being separately compiled to the output and don't show up in the search. That's for Browser-based Help. Is CHM Help different, and if so, why?

I also have several dummy invisible topics used as scratchpads, work-in-progress notes, etc.

I had previously assumed that invisible topics go into the output as separate topics only if they are explicitly linked to. I can go and de-select All Builds if it's necessary, but it doesn't appear to be so. :?

Martin.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Martin,

Hmmm... Thanks for noting this. This seems to have been changed since I wrote the help. I just tested it with CHM and the source topics in invisibles are no longer included unless there is an active link to them. I'm going to have to check this with Alex and possibly update the help... :?
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.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Martin,

Update: Nothing has changed. What is happening is that the topic is defined as a popup. If you are using JavaScript popups it is exported to the popup .JS file, so it is there but not accessible unless you link to it. The same thing happens in CHMs with JavaScript popups -- it's there, but it's only effect is to inflate the size of the CHM, it can't be found with search.

However, if you use normal plain-text popups in CHMs the invisible topics can be found with search unless you explicitly turn off their build options, because then they will be exported both to the .TXT popup file and as normal topics.

The same thing happens if you define your invisible topics as anything other than Popup -- the topics will be exported to your output as normal files unless you turn off all their build options.
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