🚀 go-pugleaf

J�rg Giencke <jg@xtra-micro.com> wrote in article
<34C1D751.2228@xtra-micro.com>...
> AbsoluteBurn@usa.net wrote:
<snip>
> A) I'm a bit worried about the easy access part. That's one of the
> biggest problems in any library. It doesn't make any sense to store all
> the information and all the solutions if one can't find it. This
> newsgroup proofs that a lot of people have trouble finding information.
> There are so many questions posted in the newsgroup that had been
> answered quicker and sometimes more competent and comprehensive if they
> just had a look at the appropriate help file.
> So, what�s the problem? I�m afraid some people prefer to let others do
> the work they�re supposed to do.  But I guess most of them have really
> tried hard and just couldn�t find it.
> Example: Over the last few months there have been about ten articles
> posted asking about setting text in and retrieving text from a dialog
> edit control. If you open the help file it�s exactly three steps until
> you are at the right point. There�s almost no way of missing the answer.
> So how come they don�t find it? Don�t they know that the help file
> exists? Don�t they know how the help file is structured? Does it mean
> they�re looking for an apple but they don�t know that it grows on trees?
> Or if they know, maybe the don�t know that the tree simply is called
> apple tree? Or, most likely, is the �search engine� to stupid or to
> confusing to support them properly?

You have raised some good points here but I don't think the original poster
intended to duplicate the help files.

As for online help, it is only useful if you know how to use it.  I
personally find online help to be most useful when I already know what I am
looking for.  For example, If I want to draw text on the screen using OWL I
know that I need to use the TDC class.  It's a simple matter to find the
TDC class reference in the online help.  But if I want to understand the
underlying architecture of the doc/view classes and the interactions
between TView, TDocument, TDocManager, TApplication, etc. I would rather go
to a book that discusses this information in a sequential way.  The online
help gives it to you in a very disconnected way.  I don't think that online
help will ever replace written documentation.

People do post a lot of questions that can be easily found in the online
help.  Some don't know that it exists.  A lot of people buy the low end
compilers that do not come with much, if any, written documentation, and
have no idea of how to use the IDE. 

Some people are completely lost.  Those that are beginning to migrate from
DOS programming to Windows programming are the most confused.  My favorite
most frequently posted question is:
-- Why do I get a linker error that says "BGI graphics are not supported by
Windows applications"  when I try to use the BGI graphics library? -- It's
obvious that some people have no clue.  They just need a gentle hint that
sends them off in the right direction.  That's what this newsgroup is all
about.

> B) Let�s assume we�ve found what we�ve been looking for. Then another
> issue is the selection of explanations and code examples. What�s a good
> example, what�s a bad example and who�s going to decide that? Borland�s
> documentation for instance is a good example of a fine selection of bad
> examples. This collection of classes A, classes B, classes X, classes
> Derived, functions f() handles the issues sometimes so theoretically and
> confusing that it�s no help at all. Who�s supposed to know after reading
> two pages of source that doesn�t do anything useful but trying to do
> everything possible whether class Derived had something to do with class
> X or class A or not?
> Have a look at Borland�s documentation concerning dynamic_cast and then
> have a look at http://www.acm.org/crossroads/xrds3-1/ovp3-1.html. I
> think in 99 of 100 cases explaining something using real live issues
> like bank accounts is much easier to understand than Borland�s
> dynamic_cast<T>(*p). And it spares you unnecessary explanations like:
> �if class B is derived from class A� or �remember that class B was
> derived from class A�. It�s obvious that a savings account is a special
> case of bank account and therefore derived from bank account and you
> don�t have to be remembered even after going through ten pages of
> source.
> Coming back to the point: How can one make sure that what you�ve found
> is really helpful? How to make sure that not just only a chosen few
> understand the meaning? How to make sure that an example explains
> everything thoroughly without going to extremes and/or confusing people.
> The explanation of dynamic_cast at
> http://www.acm.org/crossroads/xrds3-1/ovp3-1.html for instance is a good
> example of a well done explanation that just stops at the point in front
> of the gate to �C++ Wonderland�, it�s a pity.

It almost sounds like you want Borland (or some other authority) to control
the content of all web sites that discuss BC++.  It's not going to happen. 
What you find to be abstract and too theoretical may be just what another
person needs to understand and solve his problem.  Everybody has their own
way of expressing their ideas.  "How can you be sure that what you have
found will be useful?", you can't until you read it.  "How can someone
determine that what he has published (at his own expense and time) will be
useful to someone else?", he can't unless you give him feedback.

> Anyway, I guess most of us would more than appreciate a �tool� like that
> and I would really like to assist.

Agreed.

And now, for the original poster.

A lot of people have made very good comments.  There are already two great
web sites that support BC++ programmers.  The OWL Sources web site has a
great selection of OWL code samples and the OWL-HOW web site discusses
several issues that Borland's online help and documentation gloss over.  I
suggest that you include links to these websites and don't duplicate their
content.  Also, surf around Borland's website.  There are a lot of useful
pages on that site that you could provide links to.  I have links to
several other useful BC++ websites as well.  

Having done that you might want to have a theme (or several themes) such as
a newbies page or an OWL page.  I suggest that you stay away from a generic
C++ page since there are enough tutorials, web sites, and newsgroups that
cover this topic already.  The theme that would interest me the most is a
website devoted to OCF and using OLE with BC++.  John Maddock's and Geordie
Cross's websites are the only ones that I have found that address these
issues.

Let me know if I can be of further help.
Scott