Remaining with Webhelp

[TeSol]

Hello,

My application relates to banking and is mostly hosted on desktops/laptops. Naturally, my output target is Webhelp. We currently don't use tablets or phones for the application - talks to do so are still on. Is there any reason for me to switch from Webhelp to HTML5? Any benefit? Pros and cons? Any advice in this regard would be appreciated.

Looking forward to hearing from more knowledgeable users regarding this.
Tesol

[devans]

I did the switch from Webhelp to HTML5 on upgrading to Flare 11. I found that even though my online manuals didn't change, users really liked the HTML5 output and the fact that the search is more like a Google search and so is more familiar to them.

[kwag_myers]

The only issue I've ever encountered is when the application does not support jQuery. But if the Help is independent of the application, it shouldn't matter (I think...maybe). It might be worth a conversation with the developers, or maybe someone in QA could test the HTML5 output for you.

[TeSol]

Thank you for your responses. I'll put the proposal to switch to HTML5 forward and see how it goes.

[ChoccieMuffin]

I was under the impression that HTML5 help has to be accessed on a server rather than on a local machine. Because some of our users may have restricted internet access and our software is generally installed on a local machine I just assumed that I couldn't upgrade to HTML5. Have I got this all wrong?

Another potential problem is that the old Htmlhelp is compiled into a neat little .chm but HTML5 isn't compiled into a single entity so my delivery would be loads of files in a folder. (Our dev team might whinge too.)

1. Is it possible for me to change to html5, given the local machine situation?
2. If it is possible, what would be a good reason to, other than that chm is really old-tech and might end up not being supported some time soon?
3. Do you have any wonderful reasons I can use to sell the idea (if it's a good idea, of course!) to my superiors?
4. How much pain would I have to go through to get 40 or so separate Flare projects to produce html5 output?

[Nita Beck]

HTML5 can indeed be locally installed.

For one of my clients, we produce an HTML5 Help system that is installed locally with a Windows application. The s/w devs have hooked up Help topics for context-sensitive access using the usual method of calling a topic ID. (We have an alias file in the Flare project with which we manage the IDs, and we give the s/w devs the header (.h) file that Flare produces.) We deliver to the s/w devs a self-extracting zip file that, during installation, extracts the contents into a folder where the s/w app expects to find it. When the user runs the application and presses F1, the app launches an IE browser window and fetches the required topic.

As in your situation, the machines on which the software application is installed have no access to the internet, so we can't deploy the Help from a server. Also, my client sells the machines (they are part of large pieces of equipment) and so can control that the only browser installed is IE.

I can't recall the specifics now, but the s/w devs had to do a little fiddling to get things like the browser's Back and Forward buttons to work correctly, but they found the solution in the Microsoft Developers Network (MSDN). We also had to make sure that "Mark of the Web" was turned on in the target, given that the output would be locally deployed.

I can't quantify the amount of pain you'd have to go through to convert from .chm to HTML5 output, but I think you'll find it not very onerous, well, if you're going to the tripane interface. You'll spend most of your time designing the skin, assuming that you want something snazzier than the default. We've branded our tripane HTML5 output to look *a lot* like the software application itself in terms of colors and fonts. It definitely looks oodles better than the old battleship-gray .CHM UI.

If you want to go all the way to Top Nav, you will have more work to do in each of your 40 projects. You can likely design the Top Nav components just once and use them in all the projects, but each of the projects will need a "home page," which can be pretty simple or can be pretty complex. (FYI that there's a recorded webinar from just this week in which MadCap's DocTeam discussed the ins and outs of crafting a home page for Top Nav. See https://www.madcapsoftware.com/demos/si ... 7994552880.)

HTH

p.s. If some of your users CAN access the internet and some of them CAN'T, you might need two versions of the Help system, one that will be installed locally (and so will be updated only when the s/w app is updated) and one that will be served via the internet (and so can be updated at any time, theoretically). If you go with this approach, the local one will need "Mark of the Web" turned on and the other won't. And I have no idea what magic the s/w devs will need to do programmatically to ensure that the right system is being called depending on connectivity or lack thereof.

[ChoccieMuffin]

As ever, Nita, you are a star! Considering I have one massive project that really wouldn't be suitable for topnav I'm likely to stay with tripane because our users will be familiar with navigating using the Contents tab.

Other than that, I think I might have to dip a toe into the HTML5 pond and see what fishies bite it.

Any reason to do it other than "oooo, look, something new, let's try it!"?

I think someone here was fretting that because the help wasn't compiled then people can just copy topics very easily from their machine to somewhere else (protection of intellectual property kinda fretting) so is there anything I can do about that? I know it's not hard to decompile a help file and copy the topic anyhow but I would like to be able to squash that objection as soon as it's raised (long on-going discussions here that have more to do with questioning what should be included in the help file in the first place).

What BENEFITS can you think of for making the change? I haven't come up with any so don't want to give myself a pile of work if there is no point in doing so.

Thanks all.

p.s. Just saw your ps, Nita - that sounds like a big objection from the dev team NOT to do it. Interesting stuff...

[Nita Beck]

Just saw your ps, Nita - that sounds like a big objection from the dev team NOT to do it. Interesting stuff...

I don't have time right now to address your excellent questions (sorry) but let me point out that in my P.S., the salient word is "might". You don't HAVE to create two different versions. You could decide to deploy only the locally installed version. That should forestall that potential objection from the devs.

[kkelleher]

One advantage of HTML5 is that it works in a larger number of OS/browser environments, though if you're app is Windows-only, this isn't a concern for you. Our users run many different flavors of Linux/Windows/Mac, so for us, it's important.

CHM isn't being actively developed by Microsoft, and hasn't been updated since 2001. And though I don't suppose Microsoft will simply drop it, it might still be a good idea to move to a more modern platform.

Thanks,

Kristen

[doc_guy]

HTML5 output creates a much better user experience than CHM help. You have more control over the design, and you can make your output easy to use and inviting to use because of the wide range of stylistic options available to you. HTML5 output works across ALL screen sizes. From old computers with low resolution, to new computers with Retina display, to handheld computers to tables, to everything in between. It may not being used on a mobile device right now, but you probably have some users with lower-resolution screens, and you have design options to make that experience much better than you can do with a CHM file. Additionally, my understanding is that the search functionality in HTML5 is far superior to the search functionality in CHM. As an author you have much more control over how an item gets ranked so you can adjust settings in a topic to make it rank higher in search results. The HTML5 search engine was rewritten for Flare 11, and from my seat, it is a sufficiently compelling reason to upgrade to Flare 11/ HTML5 output in and of itself.

And it is easier to work with and it is prettier and it is new and exciting and fun, which helps alleviate some of the tediousness of technical writing, but like you say, these reasons are harder to sell.

[Paulie]

I was involved in a CHM to HTML5 conversion a couple of years ago. I think that most of the important points are covered above. Here are a couple of other things to note:

One good thing about the customizability HTML 5 output is that you can make the help system look and feel like a part of the software product that it supports, rather than something that has been bolted on to the side. Also, if the devs host the HTML5 help in their own web browser control (rather than a standalone browser) there is a lot of integration that can be performed between the application and the help system. One of the things that we played with a couple of years back was two-way communication between the application and the help system. For example, the application could pass text into the help system via the url. Also, you could click on a link in the help system and have the application react to the event (such as a 'take me there' link in the help that causes the application to navigate to the screen that you are reading about in the help).

One other thing I worked on was packaging all of the HTML5 help files into a single self-extracting .dll file that installed the HTML5 help onto the user's local machine. This allowed the devs to include a single file in their build, rather than hundreds of help files. There was big opposition from the developers about having to include so many files, so I don't think we could have switched to HTML5 from CHM without this.

Having said that, most of the above could probably be achieved with the Webhelp output too, but it is an advantage when compared with CHM.

[ChoccieMuffin]

OOOOooooooo, what a helpful bunch you lot are!

I think on the back of your suggestions I will look to move towards HTML5 after our next release. I don't have enough visibility of my current workload (other than "there's loads and loads to do!") and I have a new team member to work with who's not very experienced with Flare so I don't think now is a sensible time to change, but I will certainly head in that direction.