Re: Standard Library Interest? (The Big Player ACT)

[Georg Bauhaus <sb463ba@l1-hrz.uni-duisburg.de>]

Marin David Condic <nobody@noplace.com> wrote:
 
: Whatever documentation is available for Charles, it isn't an integrated 
: part of the library.

I think it is, but you cannot see it :-)
Point is, you cannot make good use of the library if you haven't
understood how it works. No hypertext can help here.
No short "contextfree" subprogram description, no example
introducing more context than you had asked for.
Worse, you can waste even more time trying to find answers
for basic usage questions, as Stephane has explained.
But, you rarely *need* to dive into the detailed annotation
hypertext once you have understood how the (container) library works.
That is because it is organised in a predictable way, around
a few principles, for a well specified purpose. (Not for a massive
collection of everything.)

Would it make sense to try to explain the underlying fundamentals
in descriptions of what is built upon the fundamentals, so to speak?
Or should the fundamentals be explained elsewhere?
And OTOH you don't need so much more than to know the priciples,
in practice.
If you look at SGI's STL headers and those of other vendors derived
from them, you won't be seeing a lot of comment.
And I think many of these comments would be repetitive as well as useless.

Another example:
One could argue that SUN's Java libraries have extensive hypertext
documentation, and that Eclipse pops up relevant doc parts next to
a name denoting an item from the library.  That's useful if the
library isn't that well organised, and you have forgotten some
specifics.  But still, given typical usage of the hypertext, how
do people learn that there are "container classes" with methods,
and "static functions" to work with containers, in a "parallel"
set of classes? If they ever learn this at all.


Some similar situations:
How do you learn how to write a GUI using GTKAda, or NextSTEP,
or ...? Hypertext describing relevant subprograms seems useless to me
without prior learning, e.g. from an n-days tutorial. After that,
if you know what subprogram to use, a quick lookup table is most
helpful, and hypertext will guide you to parameter details etc.
But no earlier than after the tutorial, and only if the library
is a mess whose organisation cannot be kept in anyone's head :-)
(It appears that container libraries such as Charles or Booch's
need not be messy, but can be made consistent in your comprehension.)


: There may be any number of ways for the determined 
: user to find out what Charles does, but it isn't just standing right 
: there saying "Here I am - let me tell you more about it..."

In view of the above this expectation is maybe mislead.
Once you know the principles, you can almost guess what is in the
interface to some container. I think this is much more productive and fun.

:> (Does it help knowing that STL work began with Ada and Scheme? :)
:> 
: Nope. If I loved the STL so much, I'd run off and use C++. Ada having 
: inspired the STL and Charles having copied the STL is pretty irrelevant. 
: Its Ada saying "Me too!!!" rather than "I'm head-and-shoulders above the 
: STL!"

You would have to prove how it is possible to be head-and-shoulders
above the *principles* of STL. C++ or Ada is not that relevant here,
I think, except that Matthew Heaney writes that Charles is an
Ada library, using Ada features, not C++.

: If you want to gain users, you must make it as EASY and PAINLESS as 
: possible to get REALLY high quality stuff. Users are like water flowing 
: downhill - they seek the path of least resistance.

In the case of standard container library,
should Ada vendors follow strategies from the MS marketing labs,
in that they try to impress programmers with linked descriptions
that turn out to be no more useful than Stephane has
explained?  Does this documentation hay stack searching trigger good software
engineering in case good software engineering implies good use of
a container library in the learned ways it has been designed to be
used?
Hypertext is just a formal aspect of text structure. It does not by itself
guarantee that the links are good. Imagine an admonition link next
to every occurrence of an Iterator,

    type Iterator is ... private;
    --   and again bla blah, same as Iterators everywhere, bla bla
    --   bla bla blah bla bla, blabla blaha.
    --   BUT DON'T forget to read the introductory -->[Chapter on Iterators]

when understanding the introductory chapter on Iterators makes all the
bla bla comments nothing but a waste of time?


In an IDE, what information should be one click away, for example if it
comes to Ada reserved words? One answer to this question can be found on
http://www.htdp.org which goes along with an IDE.
Does this say something about the kind of text accompanying a library's
"standard" identifiers when the identifiers are used as starting points
of links to documentation?


Georg