Different Help for Different Web Site Domains

[LaKisha1]

I'm facing a pretty big task at work. Here's the scenario: There is a parent web site (AKA the parent domain) that has Site Help. The parent web site has multiple sub-sites (sub-domains). Each of these sub-sites need to have their own Site Help that can be different from the Site Help displayed in the parent site, but still need to use the same source and output files. Creating different projects for each sub-domain is not an acceptable option for several reasons. We need to be able to 'turn on' and 'turn off' visibility to selected pages and selected information on pages.

How can this be accomplished without generating (and maintaining separate projects) for each sub-domain?

Example of usage: The Site Help for the parent web site has three Help pages for creating a survey - 1) entering summary information, 2) uploading the survey and 3) editing the survey. On the edit survey page, there are 5 fields containing information the user may change. The Site Help for the sub-domain of this parent web site may only need to have two of the Help pages - entering the summary information and editing the survey (no uploading the survey page). Also, on the edit survey page, only 3 of the 5 fields can be changed - the other 2 fields are not to be displayed in the Site Help for the sub-domain.

How could I use the same Site Help for both the parent web site and the sub-domain (i.e., use the same source files and output files), but hide the upload survey page and hide 2 of the 5 fields on the edit survey page in the Site Help for only the sub-domain? I've already thought about using conditional build tags, but it seems to me that this would require generating different projects (i.e., different output files) and I doubt this will be an acceptable solution for our purposes.

Thanks in advance to anyone who can help me.

[Peter Grainge]

Welcome to the forum

I am not clear why you rule out merged webhelp but assuming that is something you do fully understand and have good reason for ruling out, then perhaps the use of build tags and expressions is the other way to do it.

Apply tags to relevant topics so that you can include / exclude topics in a build. Under SSL you would have multiple webhelp layouts all configured with the relevant expressions.

[LaKisha1]

Hello Peter,

Here's why I can't really use build tags (and I'm not sure what merged WebHelp is - maybe you could explain?). There may be 200 sub-domains for a particular domain. There is nobody designated to manage all of the source files for this.

Here's what happens: My job is to produce the baseline Help files for the parent domain. These get passed on to project teams who 'customize' the baseline Help files as they 'customize' the web site for the client. 'Customizations' might include creating sub-domains, etc. If sub-domains are created that are different from the parent domain, the project teams need an easy way to 'turn on' and 'turn off' help files and information in selected help files without having to generate a different set of Help files for each sub-domain. They need to be able to simply use one set of output files that are produced. There's just NO way the project teams (or the clients) could handle adding text and build tags, and generating different outputs for all those sub-domains. Hope my explanation helps you to understand the pickle I'm in.

[Peter Grainge]

Is this a new setup? I ask as what you seem to want to do is strip out certain topics for certain setups. If you start just trashing HTML files from the baseline help, those topics will still be referenced in the TOC, the Index and the Search so users will be clicking links to topics that have just been blindly stripped out. Your installers cannot tweak the TOC, the Index and the Search. If it is not a new setup, how is it being done now?

Merged webhelp is what you ruled out by saying you could not have multiple projects. This broadly is how it works.

You have a parent project that all installations have. Then you have child projects with content split between the child projects in a logical manner. You generate an output from the parent and RH creates a folder under that called mergedProjects and that in turn has one folder ready for each child. You then generate the help for each child into its respective folder.

Now where this gets useful is that having generated the whole lot, you give it to the installers. For any given installation, they just trash the child projects they do not want. The TOC, the index and the Search then automatically adjust. Much cleaner.

In your scenario what you must avoid is links between two projects where a user might have one and not the other.

BTW. It would not be the installer or the client using the build tags and generating different outputs. You would be doing that from a single project creating a library of outputs.

The only other option is each domain does have its own help but that feels as if it would be messy for the end user.

[Linux Rules]

Hello LaKisha1 -

Does each project team have a copy of RoboHelp and at least one person trained in how to use it? If so, you have a fighting chance but it will require solid planning and adherence to the procedures.

Or do they expect to modify the "base" generated WebHelp output files (html) and use that for their Help? If so, prepare for disaster, don your life vest and prepare to jump ship.

With deep sympathy,
GEWB

[LaKisha1]

OK. I've spoken with a member of management and let me start off by saying my example of usage in my first posting was a bit too in-depth. Thankfully there won't be any turning on/off of fields on individual pages. Here's what the project teams have to do when they are customizing:
1. The TOC needs to be different (dynamic) for each domain, and any reference to a title/item/name in the TOC needs to match that title/item/name in the web site.
2. They might also move TOC items around (might be different order for each domain)
3. Change names of menu items (might be different order for each domain)
4. Turn on/off entire pages (one sub-domain might display information that another one doesn't, i.e., sub-domain 6 has "Surveys" in the TOC, but sub-domain 8 doesn't have anything at all that has to do with surveys)

Allow me to provide a better example and then answer the questions from Peter Grainge and Linux Rules.

The parent domain will have a site menu. The TOC for Site Help matches this site menu. For each sub-domain, project teams may move things around in the menu, or remove some items altogether. Say, for example, the parent domain has a menu item named Surveys. In the first sub-domain, this item may be renamed as Your Surveys. In the second sub-domain, this item may be renamed as Give Us Your Feedback. Therefore, we have the same function with three different names in three web sites. The Site Help for the parent domain and each sub-domain will need to reflect the correct name.

Peter, if I understand your merged WebHelp explanation correctly, the problem is that we can't have 200 sub-folders (1 for each sub-domain, right?) and that's what makes this tricky. We definitely want to find a solution that ensures that the TOC, Index & Search only contain the appropriate information when changes are made, but the goal here is reusability without having a sub-folder for each sub-domain. Is this possible? Currently we aren't doing anything for sub-domains - this flexibility isn't available in the product yet. It is in the planning stages, which is why I've been asked to figure out how to modify our current Help to work within sub-domains. Right now the product just has one set of source files that produce one set of output files. We need to make the current files 'dynamic' enough to allow the changes without additional sets of output files.

Linux Rules,
The 'ideal' situation (i.e., what we are striving for) is that each project team will have access to RoboHelp and one person trained in how to use it. I've also already written a detailed procedure to help each project team accomplish the task of updating the help files when they do their customizations. They will be modifying the source files and generating new output based on their customizations. For each product release, I give them a list of the base product help files that I've updated and it's their responsibility to get those changes implemented in their client's customized help files.

Alas, any ideas?

[MergeThis]

As usual, complex situations call for a combination of solutions, not a single one.

A merged project can be created, then maintained and managed through a content management system (VSS, RoboHelp Server, etc.)

You can then "turn on/off" sub-projects, pages, or content by selective use of 1) multiple WebHelp layouts, 2) conditional builds, 3) removing project folders from the output, and 4) some privileging set up by your developers.

As to method 3, if you remove 50 project folders from the output directory, those subprojects will not appear in the TOC (or Index). However, as Peter mentioned, links to and from them will fail.

If you're only maintaining the master project, you can set the conditional text yourself, based on the input from the teams. For example, a topic can have multiple H1 headings, each based on conditions you create (Online & Print are supplied by default but you can create as many as you need).


Good luck,
Leon

[HKabaker]

OK, you have 200 sub-domains. Some things are manageable, but it's unreasonable to demand total variabilitity, and, in fact, I doubt they will have so many permutations and combinations across 200 products. Some commonalities should appear, I'd think.

Including and excluding material can use build expressions if you can define common patterns. Say, for example, The topic "Blue Moon" will be seen by everyone in Groups A and B but omitted for all other groups. The topic "Who's Sorry Now?" will be seen by everyone except people in Group C.

It gets complicated, yes, but if there's any commonality among clients, you can take advantage of it.

For a given label, such as "Surveys," how many variations are there likely to be? Certainly not 200, I'd guess. Can they give you an idea whether 5 or fewer variations are most likely? Do they expect "Surveys," for example, to morph into 100 alternatives?


Harvey

[Linux Rules · Accepted solution]

Your product "structure" reminds me of my client's product. Four years ago it was similar to your description. Today it has evolved and the "custom" applications are derived from a core application but EVERYTHING is kept separate, down to individual subdirectories for each topic within the app. Even my Help mirrors this application subdirectory and file naming convention. This makes it much easier to keep track of the entire project for a given customer (over 18,500 files for my client).

If possible, manage the Help project in chunks. Base the Help sub domain (subdirectory) structure right from the start. The only place this gets referenced is in the Site Help links and this is best handled as merged projects, as suggested by Peter Grainge.

The "core" Help is what you will create and provide to the project developers. Be sure to provide a detailed list of names, titles, related functions, etc. and instructions on how to import the core Help into a new Help project customize for the client. With this approach, you will need separate project directories on your server(s) as each custom generated Help project will have common file names but different content. The plus side to this is easier upkeep of the Site Help when a sub domain project is updated.

So, how is your architect approaching the application? Do you use a container (common) window with additional frames, fields, or combination thereof, that are populated based on a previous selection? Or is there a unique window based on a previous selection? How is the Help requested in the GUI - a Help button / icon, hot key - does the call trigger a JavaScript written for your application toolbar? Are you using the simple RoboHelp style context sensitive call or is it customized to read the displayed content window file name? Could use a lot more info to assist in setting up an approach.

I think you have a lot of planning ahead and more than one head-butting session with the developers. Good luck!

Regards,
GEWB
(been there, done that...got the bruises to prove it)

[Peter Grainge]

Lakisha

What you describe is virtually not possible. Yes you could create a master and keep issuing it to the installers and yes they could keep amending a copy using RH but the work would be ludicrous and there would be errors. As Linux Rules say, breaking it down to match your application is the only chance you have.

[LaKisha1]

Thanks everyone for your suggestions. It really sounds like developer-intervention will be required after I produce the master files, if indeed we go down this road. I wish we could do what MergeThis said ("can set the conditional text yourself, based on the input from the teams. For example, a topic can have multiple H1 headings, each based on conditions you create"), but there is no way for me to know upfront what conditional names I should add. Clients can ask for the names to be changed to whatever they want, and then the project teams make the changes. So for me, as the developer of the 'baseline' materials, it would be like putting "xxx" in there as the conditional text and the project teams would have to change it anyway.

Linux Rules,
I think we could really use your help. I'm not sure we have the capabilities required to carry out your idea (using a server, etc.). I think it would be wonderful if you had time to talk to two of our developers and our requirements manager...is that possible?

To be honest, I have no idea how to answer your questions, except to say that the user clicks an icon on the page to access Page-level Help (an individual HTML file specifically explaining the page they are currently looking at), and they click a link at the top of the page to access Site Help (the entire Help system).

Thanks again everyone for your input!

[Linux Rules]

Hello LaKisha -

Pick up your private message file.

Regards,
GEWB