Subject Re: OT: Help files help
> >How do you more experienced programmers out there manage this
> >plethora of information? Who has the best system? Help file pages
> >can't be searched for specific words once you've found the right
> >(a task in itself, given the somewhat cryptic headings in some
> >indexes), annotations are prone to getting lost when re-building
> >system, a group of pdf's can't all be searched at once (can
> >they?)...etc. etc.
> Well, if I may beat a drum...
> The plan was to do this (all the stuff developers need to do
InterBase) in
> one big book - the InterBase Developer's Handbook. It's been a
dream of
> mine for nearly 5 years now.

The book's a great idea but I think the problem is much more

> . . It will take 9 months' full-time writing to do it. . .

> books and the often confusing nature of the documentation, look no
> than the support lists. IB is quite peculiar, insofar as it has a
> tradition of its technical experts staying close to the community,
> many years, via support lists like this one, the Mers list in its
> days and, for the past year, the IBDI groups on
> onelist->egroups->yahoogroups. We help one another like no other
> community I've ever engaged with, in 20 years as a developer.

The support list is exceptional - but it still can take one or two
days to get a simple issue resolved because of time zones etc.

>. .
> >With regard to the IBO help files and their many brief/cryptic/non-
> >existent explanations, . .
> That is already happening. The FAQ on the IBO website is one part
of it
> (only about a third of the current FAQ entries are there yet) and
> Geoff Worboys, others and I are steadily building up a library of
tech info
> sheets to address broader topics than can be handled in an FAQ item.

FAQs are usefull but still have to be searched

> .. . As to the formats of current docs - Helpfile is Jason's
> favourite at present because it's the most portable and updatable
way to
> provide documentation for a Window-based toolset. If the component
> sometimes seems obscure, just remember that Jason maintains it
> inside the source code. It gets generated into a new version each
> there is a major release (A, B, C, etc.) so it's not always going
to be
> "fresh" for every sub-release.

This is another reason why, for me, a book doesn't address the IBO
documentation problem.

> I consider that you - free and paying users alike - get very good
value for
> money. Sometimes I'm astounded by the cheek of a few people who
join this
> list and *criticise* Jason for "poor documentation". IBO fits in
> between Shareware and Freeware. There are a few thousand IBO users
> the world and a few hundred who have paid. I've used some
> commercial third-party products with awful, useless documentation
(if any
> of you ever used the Rational Rose documentation, or Microsoft
Project, or
> the SQLServer helpfiles, you'll know what I mean!) Jason's
helpfile is
> 1000% better. You all get free support. You all get the helpfile
> free. In the past 9 months, Jason has pushed all his IBO revenue
back into
> the product documentation.

I'm not criticising Jason, and I've paid what has been asked. The
problem is once you commit to IBO in a commercial environment you
have invested a huge amount of your time and therefore money in it.
Far in excess of the sums that you pay to Jason.

In fact I WOULD PAY AS MUCH AGAIN to have someone create and maintain
a proper help file.

It is very easy with IBO to loose half a day here and there on
something that should be readily accessible in a help file via

> It's on the Agenda to review the component help over the
> months. . .<

Great! I would like to see the help source removed from Jasons
system to a 'proper' help authoring tool and for it to be jointly
maintained by Jason and others (the prime resposibility being on
another to release Jason for maximum development - which I'm sure he
enjoys most :-)).

I would like all the unfinished sections filled in, keyword search
vastly improved, examples included, FAQ content included and
reference to specific demos where appropriate - all at least to the
standard of the Delphi help files.

I would like the cost of IBO to go up or the help file be charged for
to pay for the work. When considering what it is worth I will be
considering the time and lost revenue I can save in finding answers
quickly - a lot!

Just my 2p worth - I'm probably in a world of my own ;-)