Need help with a Context Sensitive Help project

[maniac9999]

Hey everyone,

I'm the RoboHelp administrator around here - I've done some RoboHelp projects and created the procedures, stylesheets and templates for our company's WebHelp, WinHelp 2000, and JavaHelp projects, but now I'm sort of the consultant for the content authoring team that creates the help systems. I think I need to call in some help from the forum about a project I'm consulting on.

Here's the situation: A project team here thinks they want field-level help to support a web-based application. I've told them "That's fine, it's possible, just don't demand that the help author create topics for EVERY field, even the obvious ones like "Name", "Address", "Zip", etc, since there is very, very little value in doing that." We already have a very old help system that is being CONVERTED to WinHelp 2000 (from a "mocked-up" version of WinHelp) that did just that - every field in every screen was a separate topic, even if it wasn't useful. Every topic was essentially "This information goes in this field". As a result, we abandoned creating an Index, since we had about 27 entries for "Name", 13 for "Address1", 15 for "Address2", etc.

Well, I just heard back yesterday that they totally ignored my suggestion and they want to go ahead with the "all help for all fields" idea. I still think I have a chance of convincing them to choose context-sensitive topics wisely, if it can present my case clearly and be persuasive. I just found John Daigle's article about context sensitive help ( http://www.macromedia.com/devnet/robohelp/articles/context_help.html) and I'm looking at it now (very well done, by the way - thanks John!). It looks like, from first glance, that it might convince that project team that "Whoa, this context-sensitive thing is more than we bargained for", which is what I want them to think, since they have very limited resources and a help author that is VERY new to RoboHelp and WebHelp. I personally have never built a context-sensitive help project with different windows, but I have built several projects using conditional builds.

What does everyone think of this approach?

Thanks,
Jim

[Peter Grainge]

Hi Jim

I guess it depends on whether development want to pick up the cost from their budget. :-)

I maintain a number of help systems and one is a merged webhelp setup comprising over 12,000 topics precisely because it has a file for every field. For our new products I persuaded my management it was a nonsense maintaining that. I produce a topic describing a function, sometimes several topics, but somewhere in the page(s) for the function will a table or tables listing the fields. The developers map all the fields to the appropriate page and the user then has to locate the field in that table.

The users are happy with that as they can see several fields at a time plus some general stuff.

End result is a much more compact system that everyone is happy with including, most importantly, the users.

[maniac9999]

Peter,

Thanks for getting back to me so quickly. I was hoping that someone would say that. So, essentially, you create a topic for a function (NOT a screen), then create a table within the topic listing the related fields and what they're used for, what they can do with them, etc? That sounds like a better plan, and I'm pretty sure I can sell them on it. I think if I also explain that development will be responsible for matching up topics to fields and MAINTAINING it (creating their own matrix, spending extra time and money), they might reconsider.

Thanks again,
Jim

[Peter Grainge]

Yeah, lay it on with a trowel just how high maintenance and boring it will be for them. Works a treat.

[johnmccallum]

Jim,

If I am understanding this correctly, I think a good workaround is to create a limited number of topics but let the developers go ahead and create a map number to every field. You can assign multiple map numbers to the same topic.. It might make for a long .ali file but it will be a manageable project. Depending on your development environment, it might be easier for the developers to generate a map ID for each field. We use visual C++ and it automatically assigns map IDs to bits of the window frame. We just direct all of these to a single topic.

John

[Guest]

Here's a nice, convincing argument that I just thought of - the only thing wrong with it is that I don't know if it's true or not.

Does the end user's browser cache the .htm files for the help topics that are grabbed from the server? If so, consolidating the field definitions lessens the server traffic.

(Always get the server guys on your side - everywhere I've worked, they wield a big stick!)

Also, I'm a big believer in functional help topics, but I have compromised for some clients and included one-per-screen conditional topics with the field labels. John, I wish I had known about the map numbering trick back then - I would have loved to give them F1 help.

Elisa