CSH topics in TOC?

[docudramaqueen]

We are a relatively young software company, and are just now starting to develop CSH topics for various dialog boxes. Just curious what others are doing with regard to:

One: Naming conventions. This has come up a couple of times. We have a workflow topic A and it happens that we want to create a CSH topic as well, but obviously can't use the same title. Do you make "Dialog" a part of the title? What other methods have you seen to distinguish a workflow article from a CSH when the dialog title is identical?

Two: Do you include CSH topics in your TOC? If not (and that is my preference), what method do you use to make sure the topic builds? Experience has shown that just existing in the alias file isn't enough to make the topic available in the online output. I've heard from MadCap about putting files in the TOC, and then putting a condition tag of "hidden" on the topic, but the one time I experimented with it, it failed. (Can't remember why now, it was a few months ago.)

Just curious what other users are doing.

Thanks

[Nita Beck]

I use prefixes with filenames to distinguish between conceptual, task, and reference topics (and other types of topics as well). So all of my "window / dialog" topics (the ones that I expect my s/w devs to hook up for CSH) begin with "ref_", while the associated conceptual and task topics begin with "con_" and "tsk_", respectively.

I do included reference topics on the TOC, and I have the TOC set to sync with the currently displayed topic. If the user presses F1 or clicks a "Help" or "?" button to open a reference topic about a given window or dialog, the user will see where that reference topic is within the TOC, within the overall structure of the Help system. I am a firm believer that users benefit from having a mental model of how topics are organized in a Help system. With very few exceptions, I put every topic in a Help system somewhere on the Help system's TOC.

[docudramaqueen]

Thanks Nita. I do something similar with my file names, only we add the designator (Workflow, CSH, etc.) as a suffix to the file name. And I'm okay putting everything in the TOC. I'm curious as to how you modify topic titles to distinguish between, say, a workflow and a CSH topic on the same dialog box, which, obviously, only has one name. Do you change the file name only, and let both have the same title? I can't imagine that you would put a prefix like "ref_" on a topic title.

[Paul Griffiths]

On the other hand, not only do I not include CSH topics in the ToC, I don't link to them, or include them in the index or full-text search. My philosophy, strongly influenced by Michael Hughes's work on keystone concepts, is to view the CSH topic as a highly specialised form that has no relevance in any other context.

Just saying.

[rob hollinger]

Historically (HTML Help) it was very popular to keep CSH topics out of the TOC, Index, and Search. The industry in general has made a bit if a shift to include that specialized content in topics that would normally be included in these areas.

In Flare, All topics are included in the output regardless of links, TOC, Index, Alias etc. They are accessible in the output and Search.
The only way to prevent them from being in the output is to Condition them out of the build or use the option in the target > Advanced Tab > Exclude content no linked directly or indirectly from the target option.

To check this, create a test project.
Add 5 topics to it (not the TOC, just add 5 topics)
Build a webhelp or HTML5 target
Open the output folder > Content folder
Notice the topics are there.
Open the help in a browser and search for them, they will show up in the results.

[Nita Beck]

Thanks Nita. I do something similar with my file names, only we add the designator (Workflow, CSH, etc.) as a suffix to the file name. And I'm okay putting everything in the TOC. I'm curious as to how you modify topic titles to distinguish between, say, a workflow and a CSH topic on the same dialog box, which, obviously, only has one name. Do you change the file name only, and let both have the same title? I can't imagine that you would put a prefix like "ref_" on a topic title.

The titles as seen by users don't include those filename prefixes. But the titles do distinguish the type of content offered in the different topics. Here's an example. Just this week I've been documenting variables in my client's product. I have topics titled "About variables" (a con_ topic), "Variable properties window" (a _ref topic, which will be hooked up to the software for CSH), "Variable expression syntax" (another _ref topic, but not intended for CSH), and then several how-to topics such as "Adding variables" (a tsk_ topic). All of these topics appear on the TOC and all of them are searchable and are indexed.

One more point. I do include window-level CSH topics on my TOCs and in the index. But if I am producing field-level CSH topics, I do not.

[Paul Griffiths]

Rob may have inadvertently given the impression that you can't exclude topics from full-text search. That's true in HTML Help but not in WebHelp. Just clear the Include topic when full-text search database is generated check box on the Topic Properties tab of the Properties dialog.

[rob hollinger]

Rob may have inadvertently given the impression that you can't exclude topics from full-text search. That's true in HTML Help but not in WebHelp. Just clear the Include topic when full-text search database is generated check box on the Topic Properties tab of the Properties dialog.

This is true and thanks for the clarification Paul.