RE: [HATT] Help As Part Of The Programming Language?

["Rebecca Downey" <rdowney@xxxxxxxxxx>]

Hi.
I'm sending this to you because I'm uncertain how much of this is obvious.
Feel free to quote or reply on list or off - your choice.

> - is a TOC necessary? (of course)
Yes and it should be highly customizable.
Does it have to be linked to a heading level? Or can it be linked to a
special tag or attribute? I prefer the tag or attribute idea.

> - how many levels do you want in the index? (unlimited)
Unlimited should be about enough (S,AS).
How does the index handle the idea of multiple entries pointing to different
references of the same name?
After reading the posts on SourceForge, I prefer the idea of
	Dufus [1][2][3][4][5]
Go to Dufus [1]
And you get a small menu inside Dufus showing
	Dufus Next>[3][4][5]
Go to Dufus [2]
And you get a small menu inside Dufus showing
	<Previous Dufus Next>[4][5]
And so on.

> - how should other lists be supported?
I assume you mean: glossaries, hierarchies, secondary tocs, secondary
indexes, lists of other markers?

If the latter, I like the idea of special attributes in existing tags.
The ability to generate and collect this data either on the fly (within the
browser) or upon the document's generation (by the author) is necessary for
a flexible system that would be an improvement over winhelp.

> - is the tri-pane sufficient?
I think this should be customizable by the user.
If they want more - they should be able to design and add more.
If they want less (think MSDN - hide the TOC, hide the index...) then that
should be easy to do too. I think starting with the tri-pane is a good way
to go because it seems to be the most popular.

> - what buttons are needed for the reader to navigate?
You need:
	Navigational buttons (First, last, Bottom, top, previous, next)
	A button for each type of list employed (toc, index, glossary, etc)
	Functional buttons (print, search)

> - is FTS necessary?
What is FTS?

> - how important is on-the-fly configuration of material (so you can
> write one manual and produce beginner/intermediate/advanced versions)?
Very.
With shrinking budgets, most techwriters are being asked to produce more in
less time. Reusable content (dare I call it single sourcing) is one way to
go. I think the more flexible the product, the better.

> - What are your pet-peeves with WinHelp, HH, etc.?
I now use HTML Help exclusively.
FrameMaker 6.0 source > Mif2Go > CHM
My peeves are:
-- Only one topic can be linked to a help reference. If you click on help,
you should be able to get multiple pieces of information in some cases.
-- tip help is almost non-existent in HTML Help. One page for one line of
text in output is far too cludgy.
-- Stupid compiler with no error-message help.
-- Stupid compiler that doesn't check validity of cross-references. If the
file is there, it assumes that all cross-references to that file work.
Newsflash: they don't.
-- Alinks, Klinks - wha? While very useful, it's rather esoteric and I find
them to be useless and headache-prone (another reason I switched to HTML
Help).

> - What do you want improved?
-- tip help: I'd much rather see an XLST used on the dataset to serve up the
relevant tip. Cut down on the number of files and output. It would also
improve the print rendition of the help.
-- cross-file linking within the help. Automated generation of next and
previous (in Mif2Go parlance I want it automatic and across split files, not
just within split files).
-- smarter compiler. If an error appears, I want it documented. How do I fix
it!
-- smarter compiler. It should check the validity of any and all
cross-references; even if it has to launch my web browser and hit the 'net.

> - What do readers need?
-- something easy to use (like a web page).
-- something who's hierarchy is obvious (answering the question where am I
and how did I get here).

Overall, are we talking about source in XML, or HTML? I would prefer the
source to be XML as it would be easier (IMHO) to generate data retrieval
on-the-fly. It would also be a lot more customizable, as authors could
generate their own XLST as desired.

Just curious.
-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Rebecca Downey Senior Technical Writer
ITG:NBM Matrox Electronic System
1055 St Regis, Dorval, Quebec, H9P 2T4


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **