Re: Multiplatform Documentation/Help/tutorials ...

Subject: Re: Multiplatform Documentation/Help/tutorials ...
From: Megan Golding <mgolding -at- secureworks -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 11 May 2001 15:39:08 -0400

Barb (and Everyone):

I recently undertook a similar project that was just finished. We chose an HTML help platform that was home grown using (the tiniest amount of) JavaScript and HTML documents.

The user interface is web-based and makes use of cgi scripts to build dynamic pages and common formatting elements in the form of header files and CSS.

Our solution satisfied our requirements of platform independence in viewing and kept the download overhead low.

We architected the following:
1. Content was created as HTML documents, divided at a topical level into separate HTML files. Navigation between the files was written into the docs. In other words, I created a stand-alone document in several HTML files with navigation between files, as appropriate.

2. The user interface has two access points to the help system: a help button on each page for topical help and links from all field names to glossary help.

3. The user interface has hooks into the help system via href links that call a small JavaScript (that's contained in the common header for all of our pages). The JavaScript is responsible for opening a new, small browser window, pulling the appropriate HTML help file in, and putting a title on the window.

For example, here's how one of the help buttons works:
<a href="javascript:pophelp('address')"><img src="images/helpbtn.gif"></a>

The javascript opened a window and wrote the referenced file to the window.

I've used RoboHelp in the past and have noticed a lot of parallels between the two systems. I really like that my HTML files have their own navigation and could be a stand-alone document. I am free to develop help totally independently of the developers coding the user interface. From a process point of view, we had to be sure to agree on who gets to name the HTML pages (because they are called from the user interface by name). We realized this only after we had several instances of similar-but-not-quite-the-same names that caused HTTP 404 errors.

I hope this helps. Please let me know if you'd like more detail about our solution.


At 10:39 AM 5/11/01 -0400, Barb Einarsen wrote:

Hi all,

Our new project is a client/server software package. The server runs on
Linux box. The client can run on Linux, UNIX or Windows.

We need to decide what tools we should use to develop online help,
tutorials/demos and, hopefully, natural language searching/expert

The Questions:
Do any of you currently work on a similar system?
Did you use html help, java help, or 'other' for the online help system?
Is there a platform independent tutorial/demo choice?
Any other suggestions?

Megan Golding | mgolding -at- secureworks -dot- net
Technical Writer | SecureWorks, Inc.


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See or 800-463-6627 for more about our solutions.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: File naming conventions in Acrobat
Next by Author: RE: Thank You Re: Interviewing SMEs
Previous by Thread: Multiplatform Documentation/Help/tutorials ...
Next by Thread: HUMOR - "Make this Pretty" (lament of a tech writing dept.)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads