WebHelp without the frames

[dsimov]

Hello,
Flare offers several outputs: DotNet, HTML (chm), WebHelp and WebHelp Plus, and Printed formats for Word and FramMaker. I need a different output: HTML files.

In essence, I want to deliver WebHelp but without the frames and the menu provided by Flare. I want to be able to place the content in a skin of our making. I know we can use any other tool and write the HTML but I still want to be able to use Flare's functionality, and especially the tools for snippets and links.

An option is to choose a WebHelp target and use just the content from the Content folder of the output. This is a kind of hack, though. I will never be certain that I am not missing something.

Any other options or ideas?
Thanks

[RamonS]

Not from a Flare viewpoint other than the hack you already mentioned. Flare's intent is to deliver an independent help system that further allows for connection to a software application by simple means. Deviating from that opens the doors to pretty much everything and it is a bit much to expect that any software tool easily adjusts to the unknown.
I just wonder which functionality in your framework would be so drastically different than what WebHelp offers. You still want to have at least a ToC in place and ideally also a search function. That means when you only take the bare content you need to run your own search indexing (such as with squish-e) and display controls and results. Since the WebHelp skins are already quite customizable I wonder what the benefit is to roll your own other than for the sake of doing it and learning from it.

[dsimov]

I would love to be able to use the TOC, index, and search, but without the frames. Can you provide a skin where these elements are accessible as separate pages and not as tabs within the navigation frame?

Reasons the frames are a problem:

• Speed. The frames take very long to load. Our first topic takes about a second to load without the frames and 20-30 seconds to load within the frames. I do not want to make our users wait.

• Addresses. Topic addresses are not exposed. Pointing to a specific topic is tricky. The only people who can do it are our support staff, and we had to train them how to do it. Users cannot do it.

• Navigation. Getting back to the frames is tricky too. Occasionally, we open a topic without the navigation frame and the menu bar. Showing the navigation frame and the menu bar is not possible unless we point users to the Default.htm page. The closest to a solution we've found is to place a help home link in every topic.

• Misleading location. The tabs in the navigation frame do not sync with the content frame. Thus, when users follow links from within topics, the reading of the navigation frame is inaccurate. For example, users open the What's New topic using the TOC. The topic becomes highlighted in TOC. Then users follow the link to Feature 1 from within the topic. The content frame shows topic Feature 1 but the TOC still shows What's New highlighted thus misleading users that they are still looking at the What's New topic.

• Visual clutter. The navigation frame and the menu bar are useful elements; however, they make the pages look crowded. I would rather have the TOC, index, Search results, and so on, as separate pages and just link to them.

• Hidden search. A search box is available only on the search panel. It is thus hidden from view and many people may not even realize they can use search. Those who know they can search have to click the Search tab and wait for its content to load, and only then can they search.

• Bugs. The frames have certain bugs that we have to consider. For example, occasionally, clicking a link in the TOC or Index, opens the respective target without the framset; that is, the navigation is lost. The behavior is unpredictable from our point of view. Restarting the browser fixes the problem.

[QBF]

That means when you only take the bare content you need to run your own search indexing (such as with squish-e) and display controls and results.

This is the first I have heard of squich-e, however, I have used Swish-e which is an excellent open source system.

[RamonS]

That means when you only take the bare content you need to run your own search indexing (such as with squish-e) and display controls and results.

This is the first I have heard of squich-e, however, I have used Swish-e which is an excellant open source system.

Ooops, yes, swish-e it is. Seems my fingers are too fat for the keyboard.

[RamonS]

dsimov, just a few comments to the points you listed.
- speed: I agree, framesets take longer to load and render, so doing without for sure will make things faster.
- addresses: one can right click into the topic pane and get the direct URL for the topic from there, at least with Firefox
- navigation: there is an option to add the "Open topic with navigation" link to the topics when they are called directly. Clicking that link will reload the topic with all navigation options....in a frameset though.
- misleading location: I cannot agree with that. You can set the option to automatically sync the ToC to the topic. So when a user clicks a link in a topic that opens a different topic the corresponding location in the ToC is selected. A problem occurs when you have the same topic linked multiple times in the ToC, but for that case using a snippet that includes the entire page contents and inserting it into individual topics circumvents this issue.
- visual clutter: I think that is a subjective. When I look at the modern GUIs of applications they are even more cluttered and apparently people go for that.
- hidden search: yea, I agree with that one as well, especially since the search box that is in plain view in the tool bar only searches the current topic. I'd call that a bug since the browsers already have a tool for searching the current page, so there really is no need to reinvent the wheel...errr, page search.
- bugs: I haven't come across those, but that doesn't mean that they are not there. Which browsers are in use? Older browsers and crappy browsers like IE are known to have problems with standard XHTML. Or there is an issue with how the topic is linked in the ToC or Index.

You bring up several good points that haven't crossed my mind before. I learn new things every day.

[LTinker68]

• Speed. The frames take very long to load. Our first topic takes about a second to load without the frames and 20-30 seconds to load within the frames. I do not want to make our users wait.

Is the help hosted from a server or is it being loaded from the user's computer? There are other issues than the output being the reason for it to be slow to load. That said, the first time the output is loaded, it might be slow, especially if you have a lot of topics (TOC has to read them all from an XML file and build the structure around it) and/or your "welcome" page is big, such as a lot or large graphics or tables. The first time it's loaded, though, their browser should cache most of it and it shouldn't be so slow. I know one or two others have mentioned it being slow to load, but it could also be network issues, web server settings, browser settings, etc. Is it slow to load when you run it on your local computer?

• Addresses. Topic addresses are not exposed. Pointing to a specific topic is tricky. The only people who can do it are our support staff, and we had to train them how to do it. Users cannot do it.

That happens in any framed environment. You could come up with a small script that "writes" the page name and its location in the output at the bottom of every page, if you want.

• Navigation. Getting back to the frames is tricky too. Occasionally, we open a topic without the navigation frame and the menu bar. Showing the navigation frame and the menu bar is not possible unless we point users to the Default.htm page. The closest to a solution we've found is to place a help home link in every topic.

There is an option (in the skin, I think) to have a navigation link added to the top and/or bottom of every topic. It's intended for those who call a single topic via a CSH call but want their users to be able to get to the rest of the help.

• Misleading location. The tabs in the navigation frame do not sync with the content frame. Thus, when users follow links from within topics, the reading of the navigation frame is inaccurate. For example, users open the What's New topic using the TOC. The topic becomes highlighted in TOC. Then users follow the link to Feature 1 from within the topic. The content frame shows topic Feature 1 but the TOC still shows What's New highlighted thus misleading users that they are still looking at the What's New topic.

There is an option (again in the skin file) to auto-sync the TOC with the selected topic.

• Visual clutter. The navigation frame and the menu bar are useful elements; however, they make the pages look crowded. I would rather have the TOC, index, Search results, and so on, as separate pages and just link to them.

I guess that would be a matter of opinion. Many users are probably used to that type of format. You can add links to the pages that actually make CSH calls to open those panels when the link is clicked. It takes a tad more to set up, but it's an option.

• Hidden search. A search box is available only on the search panel. It is thus hidden from view and many people may not even realize they can use search. Those who know they can search have to click the Search tab and wait for its content to load, and only then can they search.

There shouldn't be any contents to load initially. It should just be a blank field. If you're worried that people won't know how to navigate through help, then do what I do -- on the "welcome" page, give a brief explanation of the features in the help, how to access them, and how to use them.

• Bugs. The frames have certain bugs that we have to consider. For example, occasionally, clicking a link in the TOC or Index, opens the respective target without the framset; that is, the navigation is lost. The behavior is unpredictable from our point of view. Restarting the browser fixes the problem.

There are a couple of bugs with one of the templates provided with Flare. The bugs have been reported, but you should submit any bugs you encounter to http://www.madcapsoftware.com/bugs/submit.aspx. I've never had that problem with using the "blank" template, but I believe the application (?) template has some of those bugs.

[doc_guy]

FWIW, if there were a frameless webhelp layout that used DIVS instead of Frames, I'd use it.

[LTinker68]

FWIW, if there were a frameless webhelp layout that used DIVS instead of Frames, I'd use it.

There are pluses and minuses to DIVs versus framesets. I don't use framesets in websites mainly because of how restrictive it is regarding being indexed by search engines (Google, Yahoo, etc.), but they may be better with framesets now. And Flare's Search feature is a nice alternative.

DIVs can be a bit problematic, but you can definitely get fancier with them.

Make sure you submit feature requests. (Doc Guy knows that, of course, but dsimov should submit some if he'd like to get away from framesets, too.)

[doc_guy]

Actually, Lisa, that was a good reminder. I didn't think about a feature request for this. I just submitted one.

[dsimov]

Thanks for the comments - I learned a few things I didn't know. Thanks for the reminder, too - I posted an enhancement request for frameless WebHelp skins.

I can further argue about the points I made yesterday but I do not think it is necessary.

[doc_guy]

In the olden days, you know, when my grandparents were first creating websites (grin), framesets solved some problems that were difficult to solve any other way. Take Flare's webhelp layout: if you were to re-create the whole thing on a single page with no frameset, even if you used divs to separate the layout, when you click on a new link in the TOC panel, the entire page refreshes and the TOC settings are most likely lost (unless you used some type of variable to show the TOC location, and some javascript on the new page interpreted the variable to re-open the TOC location). If you moved from the TOC panel to the glossary panel, then you had to refresh the page. Every page must carry the whole weight of the glossary, TOC, and index, which would significantly increase page loading times.

However we now live in a modern era with AJAX which changes everything. Now you can just refresh that part of the page that changes. If you want to switch from the TOC to the index, you can just refresh that DIV and load the index into the DIV (which you could pre-load to save time). If you want to load a new topic from the TOC, you can do that by just refreshing the content DIV. No no need to re-load all the content from the other parts of the page that haven't changed. Really, AJAX, as far as I can tell, fixes all the reasons why you'd want to use a frameset in the first place. Plus you will get faster page load times, quicker switching between topics, and cool effects you can create on the page when you move between accordion items. You can use javascript to resize the DIVS if you want, so your users can have control over how large each section is. They could even have the TOC open to one size, the index open beneath that at another size and the content window open and re-sizeable.

Maybe MadCap can release an API that would allow us to create our own targets, because I've got a web developer who would create an awesome AJAX based Webhelp that would knock the socks off of any other help authoring tool's Web-based output. Think about comparing RoboHelp's framset output with a customizable Flare-based AJAX output, and you can see who would win the bragging rights war.

Framesets are sooooo 1990s. AJAX is where it is at. And it wouldn't be that hard to do. I can't believe that MadCap hasn't already thought of it. I mean, the more I consider it, the more I can see it would be a simple way to show the world why Flare is better than the competition. It seems so obvious now. I mean, think of the possibilities!!!

Ok. Time to wipe off the drool and get back to work...

[NorthEast]

I'm clearly behind the times, I thought Ajax was a household cleaner or a Dutch football team!

I'm all for more flexibility in the navigation layout though, I find the current layout options a bit limiting.

[NickC]

DocGuy - you should be in sales! You certainly got my curiosity levels soaring so I scoured (poor English pun for users of Ajax) the web for an answer. One definition of AJAX (http://www.webdesigners-directory.com/w ... skill/AJAX):

AJAX (Asynchronous JavaScript and XML), or Ajax, is a group of inter-related web development techniques used for creating interactive web applications. A primary characteristic is the increased responsiveness and interactivity of web pages achieved by exchanging small amounts of data with the server "behind the scenes" so that the entire web page does not have to be reloaded each time the user performs an action. This is intended to increase the web page's interactivity, speed, functionality, and usability.

Can't say fairer than that...

[doc_guy]

Sorry if I was unclear! Yes, AJAX is a relatively recent way of implementing JavaScript that allows the web page and the server to update small portions of the page without having to reload the entire page. AJAX-enabled web pages allow you to do all kinds of cool things; if you've used a recent version of WordPress you've seen AJAX in action. Here is an example of a table sorting mechanism using Ajax: http://www.ajaxdaddy.com/demo-sorted-table.html

Anyway, I think an AJAX-powered webhelp output would be so incredibly awesome. If you think so to, please submit a feature request: https://www.madcapsoftware.com/bugs/submit.aspx
The more people who speak up, the more likely implementation is.

[KevinDAmery]

Is this something that would require coding on the writer's part, or would the scripts be generated based on your work in the interface? I'm ok with editing html, xml, and css code, but javascript is a few steps farther up the curve for me.

[RamonS]

Also keep in mind that AJAX puts even more burden on the client as all processing is done on the client side. So if framesets are too slow I don't think that AJAX is making things go faster, but maybe one won't notice since the kewlness factor is way up.

[doc_guy]

Is this something that would require coding on the writer's part, or would the scripts be generated based on your work in the interface? I'm ok with editing html, xml, and css code, but javascript is a few steps farther up the curve for me.

It wouldn't require any more editing than skins currently do for Flare, the way I see it. However, an API that would allow us to construct our own output would be awesome in addition to a basic AJAX-powered webhelp target.

[doc_guy]

Also keep in mind that AJAX puts even more burden on the client as all processing is done on the client side. So if framesets are too slow I don't think that AJAX is making things go faster, but maybe one won't notice since the kewlness factor is way up.

"Kewlness" factor is only one benefit, but yes processing would be done on the client side. However, I think it can be done so that lots of it happens in the background, and I don't think that it would be any slower than the current setup where you end up pinging the server for four different pages that have to be loaded as part of the frameset. Plus, once the stuff was loaded once, you wouldn't need to keep re-loading it. And if your skin didn't require certain aspects (like glossary or index) then they wouldn't ever need to be loaded at all.

[RamonS]

No, it wouldn't be any slower than the current setup, but the original issue was that the current speed is not speedy enough. So prettyfying the output doesn't satisfy the core requirement in this case. And then there are still some that disable all ECMAScript in their browsers, which if the entire output is AJAX based would give those users zilch. The easiest way around that is to require an ECMAScript capable browser in the system requirements.

[dsimov]

AJAX is just another technology; similar to frames, but a few years younger and more sophisticated. Sure, AJAX-based WebHelp would be better than "framed" WebHelp. And Flare currently supports AJAX: all those togglers use JavaScript.

What I really need is to have a choice. I want to be able to choose whether to show the TOC in a frame (or layer within the page) or on a separate page. I want to be able to have the TOC on a separate page, the Index on a separate page, and so on. Simple pages with simple navigation. It is no mandatory to have everything on one page. Having the TOC or Index, or search results, or any other supporting content in the left frame constantly visible alongside the informational content is often an overload.

[doc_guy]

See --- imagine how an Ajax enabled webhelp could meet those needs as well... The accordion "frame", or div in this case, hides itself to the left, automatically unless you pin in down (like Flare's own interface). When you hover over the left sidebar, it expands and you can see the TOC or whatever. A nifty interface makes it slide out and the content on the right reflows around it. Then when you un-hover (or whatever the right word is), the div slides back out of the way and you just have your content. That is just one possibility of what could happen if you could use an ajax-enabled output.

And, I agree with you that you'd still want the standard frame-based target as an option. There are cases where some people would want to use a frame set, and I suppose we should allow them that pain if they so choose.

But really, I'm getting ahead of myself. Who knows if MadCap is even interested. Even if the idea is REALLY cool....

[LTinker68]

As long as the content panes aren't set to refresh every few seconds. We had an application that to me seemed really slow because it had a really looooong tree list and they had it refreshing every few seconds (although part of the slow response could have been because we were going over a slow LAN to a development server). But there shouldn't be any reason to refresh a WebHelp output that often, unless you're running it from a server and you're updating help topics that frequently. Once a day refresh, or automatic refresh on launch, should be fine.

And there are additional AJAX capabilities that could be implemented, although I don't know how easy it would be to create an interface for them. Tables, for instance, could have multiple sublevels that split out of rows ("detail" rows), but those types of effects are generally more programmatically involved, although it probably wouldn't be hard to set up a few XML pages to supply the data.

Anyway, WebHelp output with an option for AJAX effects would definitely be several steps above what the competitors are doing.

[RamonS]

I am not an AJAX expert in any way, but from the little that I know it strikes me that AJAXified WebHelp would mandate the use of a server, so using the same output locally as a bunch of files would then be out? I know, it really would not be an issue as the current framed version can be used instead.

[doc_guy]

I don't think so, but I could be wrong. My understanding is that Ajax is just JavaScript, so if you can do it in JavaScript locally, then you should be able to run the Ajax locally.