SUMMARY: Dreamweaver as HAT (long)

[Tom Eagles <teagles -at- DERIVION -dot- com>]

Here are excerpts of responses to my request for opinions and experience
using Dreamweaver (and similar tools) as Help Authoring Tools (HATs).

Deborah Snavely wrote:

I've used Macromedia Dreamweaver 1.2 on Windows NT 4.0 to work on a *small*
suite of browser (IE & Netscape) help files. I like its site view, and very
much appreciate its raw HTML editing capability. 

Most recently I used ForeHelp to do a quick-and-dirty upgrade to the suite
of files so that it looked the same across all files. Unfortunately,
ForeHelp 2000 has no way to tell even its Interhelp function not to embed
JavaScript references (I miss ForeHelp 1999's vanilla HTML 3.2 setting!  I
was expecting 2000 to have an HTML 4.0 setting among its options, doggone
it.)  Got my major editing done in ForeHelp, built the project, and lifted
the HTML and CSS files only for the actual object files that went into the
product. 

Discovered the JavaScript issue when Netscape wouldn't open any of the pages
without griping about the missing .js files...and Dreamweaver let me open
and delete the header references to them instantly. But I haven't found any
way to make Dreamweaver do TOCs and indexes, and I have a lot of respect for
FH. Moreover, after my deadline was past, I was able to get info from
ForeHelp tech support about how I can create a project that does not
introduce unwanted JavaScript components.

----------------------------------------------------------------------------

Rebecca Downey wrote:

a) All my docs are created in Frame. Once my master is printed and my PDF is
generated, I regenerate the frame books without page numbers in the TOC. All
other indexes (list of figures, tables, etc) I leave the numbers in
(otherwise Frame 6.0 does not seem to keep the reference).

b) Then I use WebWorks Publisher Standard Edition to convert the book into
Standard HTML (3.2)

c) Open HomeSite and do a search and replace on all the HREF tags in the
various table of Contents other Indexes and cross-references, changing them
from FrameMaker's bizarre scripting to a more standardized format (which, by
the way, I start with <B Name="... so that when I remove the A NAMEs the
changed items remain.

d) I then open the files in Dreamweaver and use the Tag Stripper by Massimo
Fotui extension, to remove all font tags, and all remaining A NAMEs.

e) skip back to HomeSite and do a cross site search replacing all <B Name=
with <A Name=

f) Back into Dreamweaver I run a sitewide check on links, correcting them as
I find them.

g) And into HomeSite to run a validation on each page (making sure I don't
break any HTML 3.2 coding rules)

h) When everything looks right and is validated,
    - if it's going to our website: I then apply a standard template (which
includes a cascading style sheet and bits of javascript) to the site and
then send it off.
    -if it's going into an application: I send it to the software engineer
who's in charge of packaging it
with the product. In such cases  I rely on the software engineer to give me
a naming structure for the links and I use it in step (c)

Sounds confusing I know, but it takes me about a day to do it regardless of
the number of files.

How did you do your indexing and TOC?

Because I change all the A NAMEs in the file, you could say I rebuild it.
The originals were done in Frame. I use IXGEN for indexing. When dealing
with pure web applications (which are rare, but do happen) I use a program
called HTML Indexer. It's good at what it does, but not as robust as IXGEN.

I've never (set up a search engine). We have an e-commerce division that's
in charge of such things. Besides - our website is based on NT, which (so I
am told) is not the best if you want a local search engine.


I have in the past used (frames), but the more popular method is to have a
standard navigational tool (not a TOC, index, search, but rather a file
next, file previous, home sort of thing) at the top and bottom of the page
and a more detailed tool (like the TOC) on a sidebar.

Jakob Neilson (www.alterbox.com) has a series of articles about navigational
tool usage on the web. His main points are that, if you want your help
system used - you shouldn't try to reinvent the wheel. He suggests going to
a variety of major sites and looking for a style that you like and would fit
your project. You can go wild with colors and graphics (if you really want
to), but the actual navigational elements should be quite mundane.

I can't get away from using tables as layout elements, even though it is not
a recommended use of HTML, it does make things a lot easier to layout.
Frames are now consistently implemented across version 4+ browsers, but they
still have a lot of bad press. I try to avoid frames for one main reason -
they take a lot longer to test and validate. If you want to use frames - go
for it, but always make sure you test them to assure your user doesn't get a
frame within a frame, or some other seemingly unforgivable error. People
seem to be more willing to accept a 404 from your website than a framing
error.

Layers (another option) are not consistently implemented. This would allow
you to dynamically modify the content on the screen _without_ loading the
page. It's also a navigated experience - in that because they are layers,
and loaded sequentially or based on user-input, the user cannot hack into
the experience and start just anywhere. Perhaps, in a few years, this would
be a viable alternative, but not today.

Ultimately it depends on your user. Can you expect your user to have access
and be using a version 3, or 4+ browser (Netscape, Internet Explorer, Opera
...) or are they stuck using a text-based browser that doesn't like detailed
tables (Lynx)?

I chose Dreamweaver because I work with embedded web-based systems a fair
bit. Previously I used FrontPage, but I could never get FrontPage to get rid
of all its various additions. With Dreamweaver I can tell it to strip all
comments (including Dreamweaver specific ones) as needed. Robohelp and
Forehelp were interesting, but not sufficiently versatile. I do not usually
generate on-line help for windows systems, but even when I do, web browsers
and Adobe Acrobat Reader are far more common among our customers.

WebWorks Publisher looks interesting - and probably I could do far more with
the full version (no doubt removing most of mine fine-tuning listed above).
But it's the price. I'm a lone technical writer. A 600$+ one-use-tool is
very hard to justify. Which, by the way, is another reason I moved from
Robohelp to Dreamweaver, and didn't pick up ForeHelp.

I previously used RoboHelp 5.0 and 6.0. We dumped it because we began moving
to more operating-system generic tools. I looked at GoLive, but decided
against it because it was listed as a Quark Killer - and I've begun to write
up new Quark documents (marketing sheets) in FrameMaker because of
FrameMaker's versatility in regards to templates and styles. Quark is better
designed to do things on the fly, but we have a certain look with our
marketing documents and it is easier to use FrameMaker and assure that all
publications have a similar look.

-------------------------------------------------------------------------


David M Brown wrote:

> 2) how did you do your indexing and TOC?

For indexing, I hope you'll try HTML Indexer.  You can download a free demo
from our web site.

www.html-indexer.com


-------------------------------------------------------------------------


Melissa L Owsley wrote:

I create all of my files directly in Dreamweaver or in notepad.  If it is
for online I find it easier to convert from HTML to print media.  (We are a
MS Office shop <yuck!>)

I use RoboHelp's Index and TOC creation tool.  I understand that there are
some others (HiTOC, FAR, and a newer indexing tool - the name of which
escapes me.)

Did you setup a search engine? 

No, but if I did, I would simply use one of the many FREE search engines
available.  RoboHelp automatically generates a full-text search tab.

I use DreamWeaver because ALL OF THE HATTs SUCK AT HTML. PERIOD. End of
story.  I 've been doing web since 1994 and SGML since before then.  I don't
like extraneous code, it is one of my pet peeves.

Why not use Robohelp, Forehelp or WebWorks Publisher? 

See above about how they are awful HTML editors.

Did Dreamweaver save you work?

Yes, I don't spend hours cleaning up HTML code that slows my pages load
time.

----------------------------------------------------------------------------
-


Claudia Fugali wrote:


My basic question was whether it was a good idea to use Dreamweaver to
create an on-line Help file. But just yesterday the other tech writer quit,
and since I have only six weeks to do this project I won't have as much time
as I thought to experiment with creating the navigational elements myself.
So I'll be sticking with the tool I'm most familiar with, which is RoboHTML.
Alas.... 

However, I did get a lot of helpful info for anyone else who wants to 
try this -- 


1. Some tools that can help you build an HTML-based index: 

Most people recommended The HTML Indexer:  http://www.html-indexer.com They
have a demo+tutorial that you can download. Here's what the guy who works
there wrote: "HTML Indexer is intended for precisely the situation you
describe, in which you create and edit your HTML Help source files directly
in an HTML editor (rather than exporting them from FrameMaker or some other
proprietary format). So, create your help source files in Dreamweaver, and
index them using HTML Indexer--as long as you don't open a file in both
programs at the same 
time, you'll be fine." 

I also got these suggestions -- "We use CINDEX for our online indexing.  It
is great!  And not that expensive.
It works great with existing tools like RoboHTML and Dreamweaver."
http://www.indexres.com/cindex.html

"For indexing, have a look at Microsoft's HTML Help Workshop
 
http://msdn.microsoft.com/library/tools/htmlhelp/wkshp/download_main.htm
 ).
Its free, and will provide you with frameset containing a table of contents
and index that will work in any browser. The finished result is a bit ugly,
but I am sure that it can be worked on." 



2. Directions for downloading some helpful Dreamweaver extensions:  

* If you are using version 3.0 (and not 3.01) go to the Macromedia
Dreamweaver website and download the patch for 3.01 - it includes a few good
patches.

http://www.macromedia.com/support/dreamweaver/ under Downloads; Download it
and run it (remember to close Dreamweaver first.)

* Then register for the Macromedia Exchange for Dreamweaver.
* When you can get into the Exchange (I'm sorry I do not remember if you
have to wait for them to e-mail you something, or what) Download the
Extension Manager (it's on the first page) and install it.

Then return to the Exchange and:
* Select Navigation from their drop down list of items. The Navigation
Extensions include: Menu Builder by Rabi Sunder Raj, Previous Page Link by
David G. Miles and Table of Contents by Scott Richards.

The table of contents extension allows you to automatically generate a list
of all A NAMES, or one level of headers. (as an aside, if you want to use A
Names as your links, remember to use underscores (_) instead of spaces - you
can't see the difference on screen, but it does make your HTML readable by
more browsers).

* Click on the file to download it.
* And launch the Extension Manager (if it doesn't open automatically) in
Dreamweaver to handle the installation of your Extension.


------------------------------------------------------------------------


OKAY FOLKS! That was the summary.

I deleted sections that I thought would be common sense or obvious to us all
(hope that wasn't too presumptuous) to save "bandwidth." I trust that some
of you will find the info here valuable, as I did.


    ######################################
    Tom Eagles,  Documentation Manager
    Derivion Canada Corporation
    100-65 Allstate Parkway,
    Markham, Ontario  Canada   L3R 9X1
    905-947-9730 ext 252/905-947-9744 fax
    teagles -at- derivion -dot- com/www.derivion.com
    ======================================  
         "Hit any user to continue."
          -----Gerry McAvoy
    #######################################