Any Browser-based help issues?

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Any Browser-based help issues?

Unread post by Dean Whitlock »

This is a question for anyone with experience distributing browser-based help. We are doing it here on a small scale, which will be expanding very quickly soon. I have very little background in how networks work and am wondering if there are security issues or other problems that might arise when we distribute the help to more companies. I want to be able to forewarn my developers and customer service people (all four of them...small company :roll: ).

In most cases, our clients will be hosting our web-based software on their intranets. The help will be installed on their server as a subfolder within our software folder. If the user has more than one module, there will be more than one help subfolder.

Their IT folk provide access to users by adding an icon/link to our application's login page from the company's intranet home page. The help is linked from the application's pages with simple <a href> codes.

What do I need to tell our developers and the users' IT people to make sure our help links work?

Thanks
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Dean,

The most important thing is that for best results the developers must observe the standard link syntax:

index.html?topicid.htm#anchorid

It is easy to fall into the trap of thinking you can use just:

topicid.htm#anchorid

This will seem to work at first glance but if you do this the browser history will usually not work, so users will not be able to use the Back and Next buttons properly.

If you have novice users you might want to explain somewhere that clicking on a TOC icon expands and collapses entries without displaying, single-clicking on a TOC entry selects without expanding or collapsing and double clicking expands or collapses and selects.

Users should not be surprised when the TOC is completely expanded if they use a very old browser or have JavaScript turned off. This happens automatically -- the help will remain fully navigable, but the JS bells and whistles all get turned off. If you expect to have many users in this category it's best not to use JavaScript popups, which won't work without JavaScript, of course. The same applies for full-text search: no JS, no search.

The only other "issue" is that bullet characters will be smaller on Firefox and tiny on Opera. There is no way around this -- the browser programmers can't seem to agree on how bullets should be rendered. (Yell at the browser programmers if you don't like it... ;))
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

To browser programmers: ARRGH!

Bullet size, of course, is the least of my issues with the lack of compliance among browsers! :evil:

Tim, Thanks for the tips about syntax and TOC navigation. Is there any easy way to place comments in the TOC itself?

-Dean
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi Dean,
Dean Whitlock wrote:Is there any easy way to place comments in the TOC itself?
Sure, each pane has its own HTML template. For the TOC just go to Project Properties - Browser-based Help - Table of Contents. If you don't want to you don't really even need to select "Let me edit HTML code directly" on this one because you can add code above and below the TOC portion in two editing boxes. Experiment... 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Very slick! 8)

I decided to edit the HTML directly so I could add a style statement in the header to reduce the font size of my instructions by a point. (I suppose I could have done it in-line in in the top of TOC box.) In any case, 9 pt makes them unobtrusive. I like the fact that they do not appear on the Index and Search panes.

Many thanks,
Dean
Post Reply