Need Information for Accessing Help for Web Apps

[cindynotbrady]

We're in the early planning stages of moving our application to the Web. Previously, we offered our customers two forms of help: web-based help and CHM help that they could see when they pressed <F1> from the PC application. The <F1> helped is tied directly to field-level help topics in CHM.

Now that we are moving to the web, we'd still like our users to be able to press <F1> (or another key) and see the help for just that screen. I know you've directed me to some tutorials before, but I don't know enough programmer language to know which tutorial is doing what I want. (Also, I've always been confused by the word "online." Are we meaning "online" as in web with URL's, etc.? Or are we meaning "online" as meaning the program is not down but is connected to a host computer.)

Can CHM's work on a web application, or can we somehow tie the help key or help icon to specific topics in our web-based help? I've researched a little bit about how some users don't think it's a good idea to tie F keys to help when programming web applications. As you know, the <F1> key in web applications is usually already set to the Brower's help (e.g., chrome help, Internet Explorer help).

Any places you could steer me would be very helpful. I am the technical writer responsible for researching this item and presenting it to the programmers. I know some, but not a lot. I want to think long-term on this, and I really don't think CHM would be the way to go, unless you or other users have some experience otherwise.

I'm eager to hear your opinion. Until I hear back from you, I will try to research this item through Google.

Thanks!

[Tim Green]

Hi Cindy,

CHM will not ever, under any circumstances, work on the Web. Never ever. Period. It is completely blocked by Microsoft and Windows, so that option is out of the question. WebHelp is your only help option for web apps.

Theoretically it is possible to remap the F1 key in your web app so that it links to your WebHelp. Your programmers just need to poll keypress events for the F1 key scan code and respond to it withe the appropriate URL to the WebHelp in the current context (I know this is technical, but if you give them that sentence they will know what it means). Generally, however, this is considered to be a bad idea. The web browser is already an application program and your web app is running inside that program. Browsers use almost all of the function keys for their own purposes, including F1 for their help. Re-purposing those keys can cause confusion.

It is generally good practice to provide Help buttons in your web app pages instead, and these can be associated with normal URL links to your WebHelp. Context links for small items are usually implemented with little (i) or (?) buttons next to the item that display a popup. You can implement this with the V3 Responsive skins in Premium Pack 3, which allow you to display popups and topics from the help within your own web app pages, without taking the user away from your app to display the entire help in another tab or window. You can point your developers to this chapter in the PP help so that they can see how this works:

http://www.it-authoring.com/info/pp3hel ... edded.html

In addition to this, these skins also allow you to embed the entire help in a box in your own web app pages and hide and display it at will with links or buttons in your app. If you choose one with minimalist design then you don't have to do any design work to make your help match your app. This is also explained in the chapter referenced above.

[cindynotbrady]

This is great information, Tim! I am having a hard time imagining this in my mind. Do you know, or does anyone else on this site know, what this would look like in practice?

Do you mind if I try to summarize what it is I should do, and you let me know if I have this right?

1. I want to have embedded help directly in my web pages.

2. On each page, the programmers need to design a question mark (or Help? or Need Information? link) and clicking the help link (or question mark icon) should bring up a help window that discusses just that screen. In their code, they would follow similar steps outlined by Help&Manual in this link: http://www.it-authoring.com/info/pp3hel ... d_web.html

3. Writers would be responsible for creating the help information in an hmxz or hmxp file, and build those help topics into the same folder that the web page will access. Build the hmxz file using Premium Pack 3. Question: Would you suggest building it with an html, htm, or asp extension?

Second Question: Can that help topic link to other topics? I'm assuming it can as long as the topics are in the same folder as the web page? However, I envision having a Help folder within the web page application folder, and building all our help files to that Help folder, but making sure the help links point to that folder.

Third Question: Does it have search capabilities across all help topics within the folder, or would we need to put a link to search for all help topics? For example, say the web page is called Loan Payments, and the help link brings up to the main Loan Payments page topic. The main Loan Payments page links to other subtopics (such as making a payment with your credit card, making a payments using a checking account, etc.). But say someone wants to search for something on all topics dealing with non-sufficient funds. Could it have a "Search All" verses "Search current help" links?

Fourth Question: Does it still use a Table of Contents?

This is why I'd like to see some examples of what embedded web help looks like.

Thanks again.

[Tim Green]

Hi Cindy,

You've pretty much got it. See my answers to your points below. You can see a simple demo here:

http://www.it-authoring.com/info/hmpage/

Click on the Show HM Help button to show the help. It will then change to a Hide button that will hide it again. This is built in. If you then look in the About menu at the top of the page you can see how links to items in the help work. Then you can play with the links that show popups on the page without opening the entire help. This is also possible with entire topics (also on pages where the help isn't embedded at all). This isn't demonstrated on this page, but it works in almost exactly the same way. The difference is that the topics displayed like this also have a bar at the top that allow the user to open the topic in the full help in an additional tab if they want to, which then allows them to browse further.

3. Writers would be responsible for creating the help information in an hmxz or hmxp file, and build those help topics into the same folder that the web page will access. Build the hmxz file using Premium Pack 3. Question: Would you suggest building it with an html, htm, or asp extension?

That is correct. If you are using .htm-based extensions you need to use .html. You can use .asp but your programmers need to be aware that these pages are quite different from normal WebHelp, so please write to support AT ec-software.com (replace the AT with @) and check about adding any functionality that wants to manipulate the page content.

Second Question: Can that help topic link to other topics? I'm assuming it can as long as the topics are in the same folder as the web page? However, I envision having a Help folder within the web page application folder, and building all our help files to that Help folder, but making sure the help links point to that folder.

Yes, that is not a problem.

Third Question: Does it have search capabilities across all help topics within the folder, or would we need to put a link to search for all help topics?

The embedded help is fully functional WebHelp with the normal TOC, keyword index and search capabilities. You can search everything.

For example, say the web page is called Loan Payments, and the help link brings up to the main Loan Payments page topic. The main Loan Payments page links to other subtopics (such as making a payment with your credit card, making a payments using a checking account, etc.). But say someone wants to search for something on all topics dealing with non-sufficient funds. Could it have a "Search All" verses "Search current help" links?

The search function is always in the entire WebHelp. You can always use the browser's own CTRL+F search function to search for anything in the current page, of course.

Fourth Question: Does it still use a Table of Contents?

Yes, see the demo page. You won't get that in the popups, of course. However, if you use the new field-level topics function then users can proceed to Search easily by clicking the bar to open the topic in the full help, which then gives them access to search and everything else. And if you have the embedded help on the page then you have everything there right away.

[cindynotbrady]

I see it now. Thanks so much for all your help! This will be great to share with my team. Kisses and hugs from America!

[cindynotbrady]

I know you are extremely busy, but my web guys were wondering about JSON. (I really don't know what I'm doing, so excuse me if this is all wrong.) I found this article that talks about using JSON to implement web help:

http://idratherbewriting.com/2015/02/01 ... -json-api/

But this really seems like similar instructions to the ones you've given me...but just using JSON. Is it?

If you ignore this question, I'll understand. Thanks.

[Tim Green]

Hi Cindy,

The use of JSON in the V3 skins isn't something your web developers need to access at all. Here is what is happening and why:

Each WebHelp topic page actually contains the entire layout. Not just the topic content, but also the heading material at the top and the iFrames on the left that contain the TOC, Search and Index components. If all this were to be replaced when you were browsing to new topics it would take a very long time and would also use up a lot of bandwidth. Especially on mobile devices, that would make everything very slow.

So instead of doing that, we simply replace the content of the topic currently displayed on the page with the content of the topic you want to browse to. And to make that even faster, we use a compressed JSON version of only the topic content -- everything else is already on the page and does not need to be replaced at all. The compressed versions of the topics are stored in the /jstopics folder in the WebHelp directory.

Doing it this way results in a massive increase in browsing speed. Loading the topics the traditional way could take up to 2-3 seconds. Just loading the compressed JSON content takes between 15 and 200 milliseconds. That is between 10 and 200 times faster.

Your developers don't need to know about the JSON version, however, because they never need to manipulate that. If they want to change content dynamically, they only need to know that their scripts must do that AFTER the skin scripts have done their work. There is a mechanism installed to allow them to do that. You can point them to this chapter in the help for information:

http://www.it-authoring.com/info/pp3hel ... pting.html

[cindynotbrady]

Tim, you are the best! Thanks so much for that insight!