Best way to author field level help for a CHM?

[pyjamaqueen]

Hi

I have been asked to create an HTML help (CHM) system for a .Net application which will include context sensitive help at both page and field level.

I have used map ids for page level help before - i.e. assigned a map id to topics and given this list to a developer for implementation, but I have never created field level help.

I've been looking at the 'What's This?' help project wizard but am confused as to whether this is the best approach and how it fits with the project as a whole (or even if it compatible with .Net applications). Does this mean that I need two help projects for the application - one for the main help, and one for the field level help? Is there a way to create field level help without using the 'What's This?' wizard?

I am using Robohelp 7.

Any advice gratefully received!

Chloe

[Peter Grainge]

I would forget What's this help. That is what you have when you click on a query mark in the top right of a window and then point to a field. It has largely dropped out of use.

We have applications that provide CSH help at field level and others at page level with the fields clearly listed in a table. Most users prefer the latter because they can find the field easily in the page level help and they can also read the help for the other fields at the same time, as well as seeing how the use of the screen in the same topic. The whole thing comes together. We prefer it as everything goes in one topic for the screen, or a small number if it is a tabbed screen where we might have an overall screen description and then a topic per tab. Whichever we use, it is fewer topics to set up. The developers like it as there is less work for them. So the users, the authors and the developers all think it is better. Hmmm, seems good to me.

It is also significantly easier if you have to produce a printed manual.

I suggest you put those points to the powers that be and discuss them. If they do want to go with field level help, then you create a topic for each field and use map ids for each topic.

---

See www.grainge.org for RoboHelp and Authoring tips

[pyjamaqueen]

Peter, thank you!

What you say makes complete sense and I will try to swing it

Out of interest however, I have been searching on Google and found myself looking at the Flare website  - they seem to have a specific feature for creating 'DotNet help' and so now I'm wondering if Robohelp is the best tool if we are moving to a DotNet environment?  If the powers that be insist on field level access, am I going to have a problem with Robohelp?

And finally...

If I do have to go down the one-topic-per-field route (heaven forbid!) is there a way to do this so that these topics open in a small popup, without the TOC / tri-pane structure?

Thanks again!

Message was edited by: pyjamaqueen

[Peter Grainge]

DotNet is proprietary to MadCap and needs to be installed on each users PC rather than installed once on a server. I am assured that RH WebHelp runs just fine in a .NET environment.

How the help opens is up to your developers. Using URLs as described on my site, they can call the topic to open the full three pane screen or just the topic with a Show link at the top. That enables the user to open the other two panes. You can change Show to whatever you want to make it more intuitive, "See more help" for example.

What's the objection to opening the three panes? It lets the user see there is more help and where they are in the system. That's the way we do it.

You can do the same with other methods of calling the help but your developers will have to figure that out.

---

See www.grainge.org for RoboHelp and Authoring tips

[Pete_Lees]

Hi, Chloe,

As Peter notes, even Microsoft has backed away from using field-level Help in the last few years, so it may be worth trying to determine whether your users will benefit from having it available to them. That's not to say that you can't deliver field-level Help, however, as all the required methods for calling it are still available to .NET developers.

To clarify, what Madcap Software calls "DotNet Help" is just a proprietary Help viewer that the company hopes will be more modern and appealing to writers than the older HTML Help (.chm) viewer. HTML Help remains the recommended format for Windows applications, whether .NET or not, and you can use any authoring tool that is capable of outputting a .chm file to create online Help for a .NET application.

The method that your developers use to call field-level Help determines how it should be authored. If they use the standard .NET method (the SetHelpString method of the HelpProvider class), each text string is embedded in the application code itself, and not retrieved from your .chm file. More information here:

http://msdn.microsoft.com/en-us/library/system.windows.forms.helpprovider.sethelpstring(VS.71).aspx
http://support.microsoft.com/kb/821777
http://helpware.net/mshelp2/demo2/h1xNET.htm

Alternatively, developers can use the old HTML Help API to retrieve the text string from a .chm file. See:

http://msdn.microsoft.com/en-us/library/ms670082(VS.85).aspx
http://helpware.net/htmlhelp/how_to_whatsthis.htm
http://support.microsoft.com/?kbid=317406

The drawback of both methods is that the Help popups are plain text only — no graphics, text formatting, hyperlinks, etc. To work around this, some people use the third-party KeyHelp control to create feature-rich HTML popups. See:

http://www.keyworks.net/keyhelp.htm

This allows you to deliver the type of Help that you mentioned in your second message ("is there a way to do this so that these topics open in a small popup, without the TOC / tri-pane structure?").

Pete

[pyjamaqueen]

Thank you Peter(s) for your replies - it is all much clearer now!

I will be seeing the actual application and talking to the developer later this week, but from a couple of screenshots received today, I can see that some (but not all) fields do have information icons associated with them, so I doubt that I will be able to talk them out of at least a partial field-level approach. I would like to keep this is as simple as possible, and use Robohelp.

From what you have both said, I'm thinking that I can create a normal Roboehlp topic for each field (using a normal window) and assign it an ID (I would probably use a different ID prefix for field level topics). Am I right in thinking that I don't need to worry about the 'popup' aspect of these topics, since it is the API command (assuming they are using that method) which calls the topic and displays it as a standalone popup?

Thanks again for your replies, I can feel the panic subsiding

Chloe

[Pete_Lees]

Hi, Chloe,

From what you have both said, I'm thinking that I can create a normal Roboehlp topic for each field (using a normal window) and assign it an ID (I would probably use a different ID prefix for field level topics). Am I right in thinking that I don't need to worry about the 'popup' aspect of these topics, since it is the API command (assuming they are using that method) which calls the topic and displays it as a standalone popup?

No, unfortunately, that's not the case. Well, it would be if you were to go down the KeyHelp route, but otherwise you'll need to author the field-level Help as plain-text strings. These can either be embedded in the application code or compiled into your Help file. In the latter case, all the strings are stored in a single .txt file whose format is as described here:

http://msdn.microsoft.com/en-us/library/ms670130(VS.85).aspx

So, you and your developers need to decide:

• The format of popup content: plain text, or feature-rich HTML (requires use of KeyHelp ActiveX control).
• In the case of plain-text popups, where to store the text strings: in the application code, or in the Help file (requires use of HTML Help API).
• The method that the developers should use to invoke the field-level Help: .NET HelpProviders or HTML Help API (plain text in both cases), or KeyHelp (feature-rich HTML).

Hope that that's a little clearer.

Pete

[Peter Grainge]

Pete

I am not understanding why you say ordinary topics cannot be used. Doesn't the developer just call the topic written for that field?

That is what we do for webhelp. I appreciate this thread is about a CHM but don't understand why it would be different. CHMs are not my thing but I would be interested to learn what is stopping that approach.

Not disagreeing with you, I know better than that, just not understanding.

Chloe

The information buttons your developers have added are different, I think, to the query mark you sometimes see top right. I think they can program then to do whatever they want including calling the help. If correct, they wouldn't need to backtrack that work unless they decide it would be better than keeping calling the same page.

---

See www.grainge.org for RoboHelp and Authoring tips

[Pete_Lees]

Hi, Peter,

I am not understanding why you say ordinary topics cannot be used. Doesn't the developer just call the topic written for that field?

Yes, that's possible, but then the target topics are displayed in the full HTML Help viewer (though the window can be customised to hide unnecessary elements like the toolbar buttons and navigation pane). If the requirement is to create true "What's This?" Help — the sort that is displayed in a borderless, autosizing popup — then it's necessary to use the methods mentioned above.

Pete

[pyjamaqueen]

OK...I am getting there, slowly! Thanks again both for such detailed information. I have two final (I promise!) questions:

(1) If I want to go down the plain text route within Robohelp, would I add the text file as a baggage file? If no, what is the best way to compile the file with the help?

(2) If I want to go down the normal topics displayed without toolbar, nav pane and buttons, is this something the developers control, or do I need to do something clever with a specific window type for these topics?

Peter G - thanks for the heads up about the screenshot buttons, I hadn't thought of that. I hope that I can fight the case for page-level help but am preparing for the worst!

Chloe

[Pete_Lees]

Hi, Chloe,

(1) If I want to go down the plain text route within Robohelp, would I add the text file as a baggage file? If no, what is the best way to compile the file with the help?

I'd guess that RoboHelp's What's This? Composer tool will set up your project appropriately so that the text file is compiled automatically into the Help file. Adding the text file to the baggage is normally unnecessary, I think, although the Helpware article about What's This? Help does suggest doing so. In the following section of the article, adding the text file to the FILES list in the project (.hhp) file is equivalent to adding it to the baggage in RoboHelp:

http://helpware.net/htmlhelp/how_to_whatsthis.htm#chmtext

Here is a freeware tool with which you can test the popups that you've compiled into your Help file (RoboHelp may provide similar facilities):

http://frogleg.mvps.org/helptechnologies/htmlhelp/hhpoptst.html

(2) If I want to go down the normal topics displayed without toolbar, nav pane and buttons, is this something the developers control, or do I need to do something clever with a specific window type for these topics?

Yes, you'd set up a new window type in your Help file (called, say, "popup"), and then the developers would reference this in their calls to the Help file, like this:

HtmlHelp(0, "c:\app\help\YourHelpFile.chm>popup", HH_HELP_CONTEXT, 1001);

Pete

[Peter Grainge]

Thanks Pete.

You were offering a solution nearer to the developer's wishes whereas I was putting forward an alternative line. With you now.

---

See www.grainge.org for RoboHelp and Authoring tips

[Peter Grainge]

I cannot help you with [1] as it relates to the method that Pete Lees has explained and I am not sure Pete will be able to at that level as he is not a RH user.

On [2] the way your developers call the help affects how it opens. See the Calling WebHelp Using URLs page on my site. That may not be the method they use but you will get the idea.

Don't go into battle expecting to lose. You ARE going to get your points across. Don't forget there are advantages for the developers too. I haven't seen your application though so if they put forward reasons why your app needs it whereas other apps might not, then give them a fair hearing, after all, that is what you want.

---

See www.grainge.org for RoboHelp and Authoring tips