Need advice on Topic names (I'm a WebHelp newbie)

[beagley]

If your WebHelp system contains several products that might perform similar functions, how do you name your topics?

Here's a sample WebHelp Table of Contents:

-Product A
--Posting Charges with Product A
--Parrying with Product A
--Product A Setup and Installation
-Product B
--Posting Charges with Product B
--Product B Mayhem
--Product B Setup and Installation

You see the problem? I'm repeating the product name in the topic titles. I feel like I HAVE to, because this is single-sourcing and those topics have to stand alone no matter where they are included, right? but since I have the friendly TOC, I think, "Setup and Installation" is a perfectly fine topic title by itself. I want to DROP the product title. But then I'd have TWO topics in my help system called "Setup and Installation." Isn't that a bad idea?

All advice welcome. This problem is HUGE for me (multiply the above problem by 100). I have these long list of topics and "Setup and Installation" or "Posting Charges" seems to make so much more sense than tacking on the product name to EVERY topic title. With long product names, it gets ridiculous! But then, maybe that's because I'm coming at this from a "single, long manual" point of view...

Alternative that I just thought of while typing this: Maybe the TOC should just say, "Posting Charges", since the book title will clearly illustrate that it is a sub-category... but the H1 of the topic should say, "Posting Charges with Product A"?

[KevinDAmery]

I think your last idea is the best: include the product name in the topic heading, but go with the shorter version in the TOC. The reason I would include the product name in the h1 is it helps your customers be certain of what they are looking at. Also, make sure you include it in the topic title so that it appears in the title bar of the browser (i.e. the browser title bar would say "Super Duper Software - Product B Mayhem" or something to that effect).

As an aside, on the subject of naming, I would not use those names for the file names on disk. Instead, use a system that allows you to avoid spaces. If you can avoid capital letters, even better. The reasons for this are:

1) Spaces can interfere with automatic features like breadcrumb trails etc.
2) Capital letters can lead to confusion on unix based web servers (basically, Windows systems consider boo.htm and Boo.htm to be the same file name, but unix systems consider them to be two distinct file names - so if you mess up the capitalization in any of your links, on a unix web server your customers will get a page not found error). If everything is lower case all the time, you reduce the chance of bad links.

An example of file names would be:

producta_post_charges.htm
producta_parrying.htm
producta_setup.htm
productb_post_charges.htm
productb_mayhem.htm
productb_setup.htm

[LTinker68]

Also, if the content of the topics is similar enough, then you can use one topic for both products and apply conditional tags to the content that is specific to just one product. If the content is too dissimilar, then one file per product makes sense, but if all that's different between a process for Product A and Product B is two or three steps, then use one topic and apply conditional tags to the three steps that are applicable only to Product A or Product B, whichever is the case.

Also, you can use variables for the product name, and in the target for each project, specify the correct product name. For instance, in your project variable set you may have a variable called "productName" and set its default value to "Product A". As you're authoring content and insert the variable into the topics or TOC entries, it'll appear as "Product A". But in the variable set inside the target for Product B, you change the value of the "productName" variable to "Product B". Flare will switch the value of the variable at build time, depending on which target you're building and which value you specified for that variable in that target.

[forfear]

1) Spaces can interfere with automatic features like breadcrumb trails etc.
2) Capital letters can lead to confusion on unix based web servers (basically, Windows systems consider boo.htm and Boo.htm to be the same file name, but unix systems consider them to be two distinct file names - so if you mess up the capitalization in any of your links, on a unix web server your customers will get a page not found error). If everything is lower case all the time, you reduce the chance of bad links.
An example of file names would be:
producta_post_charges.htm
producta_parrying.htm

This is the convention i use as well. A bit more of a carryover from the RoboHelp X5 days actually. Nonetheless, to Flare 4 i think it doesn't really matter if you are compiling to webhelp, because you can now set Flare to automatically do the 2 points above as mr Kevin recommends..ie. lowercase and insert underscore where spaces are found in the filename for webhelp outputs...

There is a section in the book Single-Sourcing by Kurt Ament that also proposes with good measure, to separate your topic by types...(You don't have to follow the DITA conventions but you can add your own ones)i.e.

Concept topics
About_XYZ.htm
About_parrying.htm
About_charges.htm

Task topics
Parrying_charges.htm
Adding_XYZ.htm
Deleting_XYZ.htm

Reference
Ref_troubleshooting_charges.htm
Ref_system_params.htm
Ref_datetime_variables.htm
Ref_databases.htm
Ref_naming_conventions.htm

For snippets you could create types like
Definition lists
Dl_ChargeTypes
Dl_ChargeAdminOptions

Figures
Fig_Charges
Fig_Roles

IMHO, i haven't done this myself our topics...just partially for images and some common Flare project items (stylesheets, varsets,condsets).
Converting 600+ topics, 300 over images takes quite a bit of time out of even the most patient, passionate individual.
Am doing it eventually project wide, with discussions within our teams, but am doing this phase by phase really out of necessity.
Necessity is the mother of invention...so i've heard...
Am doing a fairly large global project linking project with Flare 4.0 now. Its great once our first prototype was out but its slow going. Takes quite a bit of mental strength but i guess there is light at the end of the tunnel eventually.

Some planning and just sitting back with Microsoft Word, in the Outline view, to do a rough topic/chapter map outline of where key topics should be simplifies things a bit.

[forfear]

aah yes just a summary of lessons learned of working on a project like this, i am putting in this thread
http://forums.madcapsoftware.com/viewto ... =13&t=7614

[NorthEast]

One other suggestion for your project is to use search filters, so that when people use the search they can choose to only show results for product A or product B.

To do this you would first add concept entries in each topic, e.g. add a concept entry of "A" in all topics for product A, "B" for topics in product B, etc.
Then you set up a search filter set, e.g. create a filter called "product A" and link it to the concept "A", etc.