| Subject | Re: [IBO] OT: Help files help |
|---|---|
| Author | Helen Borrie |
| Post date | 2001-02-07T07:07:09Z |
At 05:47 AM 07-02-01 +0000, you wrote:
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. Last year I set up a project to do this book,
not a trivial exercise, but the willingness of content contributors to
participate was very exciting. If you haven't seen the outline and the
plans, take a look at http://www.interbase2000.org/ib_handbook.htm.
Well, the project has been on hold now since the end of July, for lack of
sponsorship. More than once, Jason offered to assist with funding but I've
held him back, knowing how much of his own money he has already thrown at
the IBDI's activities to (successfully) save IB from the gallows. Quite
simply, no matter how much I want the book to happen, I refuse to accept
that it's the responsibility of one man of modest means to fund everything
the IB community needs.
I would love to be in the position of being able to get this crunching
along. It will take 9 months' full-time writing to do it. I don't have
the means to stop other work and dedicate my time to the book. I doubt I
shall ever be in a position to do that.
Publishers have rejected the project as "too huge" to risk investing
in. Some have expressed interest in looking at the manuscript when it's
finished.
I've recently updated the IBDH translator group lists, as I feel the need
to resolve the IBDH project one way or another. The translators put in a
huge amount of effort over several months of last year, to ensure that
material in the English IBDH would be translated to German, French,
Spanish, Portuguese and possibly some other languages, too, allowing the
IBDH to hit the bookshops in several languages simultaneously. There
is/was a "one-worldness" about the project and a determination for
technical excellence and accuracy. I don't wish this to go away.
This is to say, I have a book plan (the combined work of many) and a
development plan. I have contributors, I have translators. What I have
not is money to pay the rent whilst I write it.
One of the sad offshoots of IB's user base becoming dominated by people who
got the database for nothing, is that they seem to want EVERYTHING for
nothing. Most want to take the free database, the free support, the free
books, the free enhancements (nobody gets paid in Firebird!) and want to
put nothing back in return. (The IBO community is exceptional in this
regard - the freeloaders seem to get stamped down pretty quickly around
here <g> and we are highly fortunate to have some VERY skilled folk around
to help with enhancements and support.)
If you want to understand how IB-ers got their skills despite the lack of
books and the often confusing nature of the documentation, look no further
than the support lists. IB is quite peculiar, insofar as it has a long
tradition of its technical experts staying close to the community, through
many years, via support lists like this one, the Mers list in its happier
days and, for the past year, the IBDI groups on
onelist->egroups->yahoogroups. We help one another like no other developer
community I've ever engaged with, in 20 years as a developer.
(only about a third of the current FAQ entries are there yet) and Jason,
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. We
would welcome (a) wish lists for specific topics and (b) new demo
projects. We still have plenty of holes to fill but it would be terrible
if any of you believed Jason wasn't doing anything about documentation.
handbooks. 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 help
sometimes seems obscure, just remember that Jason maintains it himself,
inside the source code. It gets generated into a new version each time
there is a major release (A, B, C, etc.) so it's not always going to be
"fresh" for every sub-release.
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 somewhere
between Shareware and Freeware. There are a few thousand IBO users around
the world and a few hundred who have paid. I've used some expensive
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 for
free. In the past 9 months, Jason has pushed all his IBO revenue back into
the product documentation.
It's on the Agenda to review the component help over the forthcoming
months. YOU can help us to prioritise this mammoth task by REQUESTING the
sections you most want clarified. I'm the one who is collating stuff and
writing it up; and I'm also developing "IBOBase" for storing all the
documentation, wish lists, etc.
and an excellent volume on data modelling. I also have C.J.Date's book on
database theory, in which I dabble. Mind you, I have learnt *heaps* about
IBO by writing about it. <g> I also contribute a lot to support
lists. You'd be surprised how often my postings come straight out of the
help file...
Cheers,
Helen
All for Open and Open for All
InterBase Developer Initiative ยท http://www.interbase2000.org
_______________________________________________________
>How do you more experienced programmers out there manage thisWell, if I may beat a drum...
>plethora of information? Who has the best system? Help file pages
>can't be searched for specific words once you've found the right page
>(a task in itself, given the somewhat cryptic headings in some
>indexes), annotations are prone to getting lost when re-building your
>system, a group of pdf's can't all be searched at once (can
>they?)...etc. etc.
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. Last year I set up a project to do this book,
not a trivial exercise, but the willingness of content contributors to
participate was very exciting. If you haven't seen the outline and the
plans, take a look at http://www.interbase2000.org/ib_handbook.htm.
Well, the project has been on hold now since the end of July, for lack of
sponsorship. More than once, Jason offered to assist with funding but I've
held him back, knowing how much of his own money he has already thrown at
the IBDI's activities to (successfully) save IB from the gallows. Quite
simply, no matter how much I want the book to happen, I refuse to accept
that it's the responsibility of one man of modest means to fund everything
the IB community needs.
I would love to be in the position of being able to get this crunching
along. It will take 9 months' full-time writing to do it. I don't have
the means to stop other work and dedicate my time to the book. I doubt I
shall ever be in a position to do that.
Publishers have rejected the project as "too huge" to risk investing
in. Some have expressed interest in looking at the manuscript when it's
finished.
I've recently updated the IBDH translator group lists, as I feel the need
to resolve the IBDH project one way or another. The translators put in a
huge amount of effort over several months of last year, to ensure that
material in the English IBDH would be translated to German, French,
Spanish, Portuguese and possibly some other languages, too, allowing the
IBDH to hit the bookshops in several languages simultaneously. There
is/was a "one-worldness" about the project and a determination for
technical excellence and accuracy. I don't wish this to go away.
This is to say, I have a book plan (the combined work of many) and a
development plan. I have contributors, I have translators. What I have
not is money to pay the rent whilst I write it.
One of the sad offshoots of IB's user base becoming dominated by people who
got the database for nothing, is that they seem to want EVERYTHING for
nothing. Most want to take the free database, the free support, the free
books, the free enhancements (nobody gets paid in Firebird!) and want to
put nothing back in return. (The IBO community is exceptional in this
regard - the freeloaders seem to get stamped down pretty quickly around
here <g> and we are highly fortunate to have some VERY skilled folk around
to help with enhancements and support.)
If you want to understand how IB-ers got their skills despite the lack of
books and the often confusing nature of the documentation, look no further
than the support lists. IB is quite peculiar, insofar as it has a long
tradition of its technical experts staying close to the community, through
many years, via support lists like this one, the Mers list in its happier
days and, for the past year, the IBDI groups on
onelist->egroups->yahoogroups. We help one another like no other developer
community I've ever engaged with, in 20 years as a developer.
>With regard to the IBO help files and their many brief/cryptic/non-That is already happening. The FAQ on the IBO website is one part of it
>existent explanations, I wonder if we couldn't all be adding to these
>via a web-based (IB?) database, as we find and solve various
>problems. This could relieve some of the pressure on the main
>responders to this list, provide a single(?) point of reference for
>many IBO queries, as well as let the rest of us feel we were able to
>contribute in some small way. Is this possible? (It's beyond me, I
>might add :-) )
(only about a third of the current FAQ entries are there yet) and Jason,
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. We
would welcome (a) wish lists for specific topics and (b) new demo
projects. We still have plenty of holes to fill but it would be terrible
if any of you believed Jason wasn't doing anything about documentation.
>I've convinced myself that it's more important to be able to find theHeck, I've been using IB for five years and I *still* need the
>right answer quickly, than to try and remember it all, especially
>given my rapidly reducing neuron count.
handbooks. 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 help
sometimes seems obscure, just remember that Jason maintains it himself,
inside the source code. It gets generated into a new version each time
there is a major release (A, B, C, etc.) so it's not always going to be
"fresh" for every sub-release.
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 somewhere
between Shareware and Freeware. There are a few thousand IBO users around
the world and a few hundred who have paid. I've used some expensive
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 for
free. In the past 9 months, Jason has pushed all his IBO revenue back into
the product documentation.
It's on the Agenda to review the component help over the forthcoming
months. YOU can help us to prioritise this mammoth task by REQUESTING the
sections you most want clarified. I'm the one who is collating stuff and
writing it up; and I'm also developing "IBOBase" for storing all the
documentation, wish lists, etc.
>Hoping to learn how the better organised amongst us function,I buy books. I have a couple of good books on SQL, several Delphi books
and an excellent volume on data modelling. I also have C.J.Date's book on
database theory, in which I dabble. Mind you, I have learnt *heaps* about
IBO by writing about it. <g> I also contribute a lot to support
lists. You'd be surprised how often my postings come straight out of the
help file...
Cheers,
Helen
All for Open and Open for All
InterBase Developer Initiative ยท http://www.interbase2000.org
_______________________________________________________