Developing WebHelp for Different App. Scenarios

[LuckyClover]

We are developing WebHelp projects for several of our Web-based applications. One of our applications has a unique set up, and I am not certain how to approach creating the Help system.

The application, "Simple", has a menu that allows users to access another application "Simon", if they have opted for such a configuration. Basically, the user would have to purchase both Simple and Simon. In this scenario, the Simple WebHelp would only contain a subset of topics from the Simon WebHelp. There are cases, however, where customers would only be using Simon, and would not have access to Simple, unless they upgrade.

For the Simon application, users need to have access to that Help, exclusively.

One option is to develop separate WebHelp: A complete system for Simple and a complete system for Simon. For the Simple/Simon application combination, maybe we could use conditional build tags for the relevant, imported Simon topics. But then, we would have duplicate data. How do we account for the Simple/Simon scenario? For a software upgrade from Simple to include access to Simon, how to we create the Help so that both Help contents are addressed (so that there is some "trigger" that knows an upgrade has happened and the correct Help displays). Can we have one merged Help system that can have conditional tags for: Simple Help only, Simon Help only, and Simple with a subset of Simon topics only, and that this one Help file can be attached to the application, and when there is an upgrade, the appropriate Help will display? If so, what is the recommended approach for this? THANK YOU FOR YOUR HELP!

[Guest]

Hello LuckyClover,

Welcome to our community.

See if this Thread can give you a pointer.

Hope it helps. |If not, please post back.

Brian

[LuckyClover]

Hi, Brian. I just wanted to say "thank you" for the reference. I printed the build tag options discussion, because it will very likely apply to our case (topics with multiple tags). Thank you for the helpful reference!

[Peter Grainge]

Welcome to the forum.

If only one person is working on the project then it might be easier to work with conditional build tags.

If multiple authors are involved but you are using source control, it might still be easier to use conditional build tags. With multiple authors but no source control, then merged webhelp will allow one author to work on one project while another works on another project. One person needs to be responsible for generation.

You say "...the Simple WebHelp would only contain a subset of topics from the Simon WebHelp. There are cases, however, where customers would only be using Simon, and would not have access to Simple, unless they upgrade." The first sentence makes it sound like Simple is a lighter product while the second sentence makes it sound like you upgrade from Simon. I am going to use the terms Generic (for topics that everyone must have), Product A (for topics that are unique to a product). Add Products B, C etc to suit.

If you use conditional tags you create several build expressions to generate outputs that suit the different content sets that you want. It is then up to your developers to deliver the appropriate version.

If you go for merged webhelp and assuming you are using the structure described in my topic on merged webhelp, the parent project is just a holder. Generic, Product A, Product C and so on are all child projects. You deliver all to the developers and they install all of them. Then they cripple the products you do not want by renaming that child's folder under mergedProjects. The parent will not then find that folder so it will not include the content in what the user sees.

Create a simple setup or download the demo to see how it works.

[Chet Zeshonski]

Avoid duplicating data at all costs! Instead, use conditional build tags. I'm going to assume the following:

1. The interface that provides access to Simple and Simon incudes features that apply to both applications. For example: navigation menus that provide access to individual modules, a Help menu, etc.
2. Simple-only users can access modules not available to Simon-only users.
3. Simon-only users can access modules not available to Simple-only users.
4. Combination users can access all modules.
5. The user must log in to a secure site to use the application, and the verification software can determine the user's rights (Simple-only, Simon-only, or combination).

Here's the solution:

1. Create topics for each module/feature.
2. Create two conditional build tags: Simple and Simon.
3. Apply the Simple tag to Simple-only features (i.e., features not available to Simon-only users).
4. Apply the Simon tag to Simon-only features (i.e., features not available to Simple-only users).
5. Create three WebHelp layouts: Combination, Simple, and Simon.
6. Define the build tags as follows: Combination has no build expression, Simple excludes the Simon tag, and Simon excludes the Simple tag.
7. Publish the different outputs.
8. Provide three separate links to your application developers. Their job is to provide different links to the Help system depending on the user's rights (Simple-only, Simon-only, or Combination).

And that's it!

[LuckyClover]

Thank you for the detailed suggestion! I have just a few more questions: In the scenario that you provided, are both the Simple and the Simon WebHelp projects separate, or is this one WebHelp project that uses the different build tags? Can we keep the Simple and the Simon project separate? Also, for the combination, I think I may need a third build tag, because in the Simple and Simon combination scenario, the majority of topics will be Simple, and only a subset of topics will be Simon--the combination will not include every topic from the Simon features. How would the process work, then?

[Chet Zeshonski]

Just FYI: I work with a project very similar to the scenario you describe. All of our subscribers use our software to collect and store data. All of them also have access to a subscriber-only website. Some of the subscribers use desktop-based software and a SQL database to store data; others use Internet-based software and our servers to store data. The Internet-based software is housed within the subscriber-only website. So all users can access the website, but the Internet-based users have access to a wider range of options.

Accordingly, the Help project for the subscriber-only website has four conditional build tags:

1. Internet-only
2. Desktop-only
3. Print
4. Online

The Desktop-only and Print tags are used at the content level (i.e., to mark text within a topic); the Internet-only and Online tags are used at both the content and topic levels. This allows me to produce four seamless outputs:

1. Printed documentation for desktop users (excludes Internet-only and Online)
2. Printed documentation for Internet users (excludes Desktop-only and Online)
3. WebPro output for desktop users (excludes Internet-only and Print)
4. WebPro output for Internet users (excludes Desktop-only and Print)

The WebPro outputs are published to an instance of RoboEngine; each contains a link to the appropriate printed document. The subscriber-only website picks up on the user's software type at login, and the link to the Help system changes appropriately. (Note that I didn't have anything to do with that; I simply explained the situation to our Web developer, and he made the necessary coding changes.)

The bulk of the work involves setting up the build tags and outputs and thinking about how you need to approach your content. Ultimately, however, the tags provide a lot of flexibility without the need for duplication.

[Chet Zeshonski]

You're welcome. The scenario I described is a single-project scenario that uses multiple build tags. My experience with merged projects is very limited, but I'm sure members of the forum can provide direction.

I can better answer your combination question if you provide a detailed list of possible combinations. Your descriptions, although helpful, are too vague for me to draw any definite conclusions. Based on your first post, I have assumed that your users will fall into one of three categories:

1. Simple-only: All topics associated with Simple should be included in the Help system; none of the topics associated exclusively with Simon should be included.
2. Simon-only: All topics associated with Simon should be included in the Help system; none of the topics associated exclusively with Simple should be included.
3. Simple-Simon combination: All topics should be included.

In this case, you simply create two build tags (Simple and Simon) and three outputs (Simple, Simon, and Combination). The Simple tag is applied to all Simple-only topics; the Simon tag is applied to all Simon-only topics; any topic that applies to users of both systems is left untagged. The Simple-only output is built to include Simple (or exclude Simon); it will include all topics tagged with the Simple tagged plus all topics left untagged. The Simon-only output is built in a similar fashion. Finally, the combination output is built without conditional expressions; it will include all topics.

Judging by your last post, however, your situation may be more complicated. Can you provide more information?

[LuckyClover]

Hi. I am sorry for not being more clear. Your understanding of the different scenarios is correct, with the exception of a portion of #3:
1. Simple-only: All topics associated with Simple should be included in the Help system; none of the topics associated exclusively with Simon should be included. Yes.
2. Simon-only: All topics associated with Simon should be included in the Help system; none of the topics associated exclusively with Simple should be included. Yes.
3. Simple-Simon combination: All topics should be included. (Half correct: All Simple topics must be included, but only some of the Simon topics are to be included, because the Simple user will not have access to the full-blown Simon application--only certain components of it.)
One of the Help authors is in favor of having separate Help projects, but it seems that it would be easier to just have one project under version control, with two authors working on it and using the applicable tags for their content. I am not sure how to apply tags to the #3 option: I think that a third tag (Combo) may have to be created. We also use a custom Skin for our WebHelp projects, and am wondering whether the appearance of that can be somehow controlled, given the different build options, or if we will have to use one.

[Chet Zeshonski]

In that case, LC, you should introduce a "combination" tag (or name it something Simon-specific, such as "Simon subset"). Apply the tags to topics like so:

1. Simple tag: Apply to Simple-only topics.
2. Simon tag: Apply to Simon-specific topics that are not included in the combination application.
3. Combination tag: Apply to Simon-specific topics that are included in the combination application (as well as the Simon-only application).

Next, define three WebHelp layouts: Simple, Simon, and Combination. Define conditonal build expressions for each as follows:

1. Simple layout: SIMPLE (includes topics tagged "Simple")
2. Simon layout: NOT SIMPLE (includes topics tagged "Simon" and "Combination")
3. Combination layout: NOT SIMON (includes opics tagged "Simple" and "Combination")

If you have topics common to all three options, don't tag them; any untagged topic/content is automatically included in each output. You can customize the skin for each project; skins are defined on their own but selected for each layout. (So layouts 1, 2, and 3 above can each feature a different skin.)

If you have additional questions, just post 'em.

[LuckyClover]

You are a treasure! Thank you for the additional Help. I think the next step is to experiment using your guidelines, learn, and ask questions if I get stuck. For now, the dark clouds have cleared!

[Chet Zeshonski]

UPDATE: If I understand your scenario correctly--and it's late on Friday here, so bear with me because I may have overlooked something--you can accomplish the desired three-way split with only two conditional build tags.

First, define two tags ("Simple" and "Simon"). Next, apply them to topics as follows:

1. Simple tag: Apply to Simple-only topics AND any "Simple-Simon" topics included in the combination application. Do NOT apply it to Simon-only topics.
2. Simon tag: Apply to Simon-only topics AND any "Simple-Simon" topics included in the combination application. Do NOT apply it to Simple-only topics.

Next, define three WebHelp layouts: Simple, Simon, and Combination. Define conditonal build expressions for each as follows:

1. Simple layout: NOT SIMON (excludes all Simon-only topics plus all combination topics)
2. Simon layout: SIMON (includes all Simon-only topics plus all combination topics, i.e., the full set of Simon-specific topics)
3. Combination layout: SIMPLE (includes all Simple-only topics plus all combination topics, i.e., all of Simple plus the subset of Simon topics marked as combination topics)

Note that these are essentially "mirrors" of the layouts I defined in the triple-tag approach in the previous post.

Again, topics common to all three options should not be tagged.