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

[Marin David Condic <nobody@noplace.com>]

Georg Bauhaus wrote:
> 
> 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.

There's nothing wrong with an "Overview" document - or even a textbook 
on the guiding principles or any other huge bulk of prose anyone cares 
to write. Did it come with the .ZIP file? Did it install somewhere plain 
and obvious when installing the software? If the answer is "No" then all 
that documentation sitting on someone else's shelf didn't help me one 
little bit. And having a hyperlink from the IDE that eventually reaches 
the "Overview" cannot possibly hurt, can it?

> 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.

Maybe so. I could probably take *any* library of *any* type with even 
poorly organized, inconsistent structure and, so long as it was, say, 
under a dozen-or-so packages or a 100_000 lines of code overall, I could 
probably *memorize* the whole thing. I'd never need to refer to the 
document at all. So what? I'm talking about having a *VERY* large 
library - possibly something built on top of an existing container 
package such as Charles. There's *no* way that someone is going to keep 
every detail in their head. They're going to need easily accessible, 
high quality documentation to do that. Standing around saying "Well if 
you understood the philosophy of this massive library, you wouldn't need 
such a thing" is probably not going to be very convincing to the uninitiate.



> 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.)
> 

Yeah, but see above. I don't need documentation for a couple-of-dozen 
packages (although it would be nice) if I can read every bit of it, 
understand it and use it regularly. I'll end up memorizing everything I 
need to know. But I'm talking about something substantially larger than 
that. You could drop something like that in someone's lap and tell them 
that "Any *competent* programmer" could figure it out..." Or you could 
give them every possible bit of help imaginable and hope this encourages 
them to eventually use it. Which is more likely to be successful from a 
marketing standpoint?


> 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?

There's nothing wrong with a "Fundamentals of the Conventional Ada 
Library" book being written. Or even a "Conventional Ada Library for 
Smart People (Because The Dummies Are Using C++)" book. There can be as 
many books as you like. The more, the merrier. However: A) That doesn't 
eliminate the need for something that gets you detailed instructions on 
a specific package, class, subroutine, type, etc. as you're busy 
programming, B) Hyperlinking that documentation and getting there via 
the IDE is not A Bad Thing, and C) Whatever documents you have ought to 
come with the distro and install somewhere useful (Gnat does a pretty 
good job - its right there in my Start menu...)

> 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.
> 
I never said that a hyperlinked reference manual was all there is to 
documentation. I said it was an essential part of what developers these 
days consider "Professional" and its part of what they pay money to get. 
They also buy books on the subject, so that's a good idea as well. But 
producing all this stuff for something substantially bigger than a 
container library is *difficult* and *expensive* so don't expect it is 
going to get done properly by an all-volunteer crew.

> 
> 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,

And the last time I looked at GtkAda, it didn't have a really good 
overview document sitting around in the distro either. I agree - staring 
at the subroutines and whatever related documentation might have been 
there (even if hyperlinked) is not an effective way to learn something 
like GtkAda. When I observed that there wasn't a good "Getting Started" 
or "Walk Through" example text or a really thorough manual, I'd get 
pointed to the underlying C/C++  product - Gtk - and told I should study 
some of the on-line documents for that. (And then explain to me why I 
want to bother using Ada if everything is there for the C++ version and 
Ada is always trailing behind?) Or I was told I could go struggle 
through the process of learning it and then I could volunteer to write a 
document and give it away free of charge. Guess what? I didn't labor 
away freely for the benefit of someone else's product.

This is a real problem with the freebie sort of software. If the future 
of Ada depends on people laboring away for free to produce something 
that will somehow overtake and exceed the capabilities we see with 
languages that have commercial backing, then Ada is in sad shape. 
Real-world developers with real-world problems to solve can't wait 
around for "One Day, Its Going To Be Great - Just You Wait And See...." 
They need something *NOW* that satisfies all those needs they find 
fulfilled in commercially backed products with lots of industry support.



> 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.)
> 
Again - something relatively small like a container library can survive 
without much documentation. Something relatively large - like the MFC, 
for example - needs something a *LOT* better. If Charles or Booch expect 
to grow into a bigger creature good quality documentation is a must.


> 
> 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++.
> 

I don't know how something is going to be made head-and-shoulders above 
the principles of the STL. What I *do* know, is that if you don't do 
something *better* than the STL in *some* respect, nobody has much 
incentive to move from a major, world-wide, accepted, dominant, 
huge-market-share language like C++ to an obscure, withering, 
niche-market language like Ada. I like Ada, but by any realistic 
assessment of the marketplace, it has only a small share and that has 
major disadvantages when someone is confronting the choice of selecting 
a language for their project. You'd better offer them something 
*WAY-MORE* than what they get elsewhere if you hope to win them over.



> 
> 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?  

Only if they hope to win market share. All the intellectual arguments 
that say "Microsoft documentation sucks" can be right and true and good 
and noble - and completely ignored by the marketplace. Do you want to be 
right? Or do you want to win?

What I can say about Microsoft is this: They may not be perfect, but 
with some of the things they have supplied WRT programming languages in 
terms of well-integrated tools and documentation - I have yet to see it 
equaled by anything for Ada. GPS is really nice and a step in the right 
direction. However, it *DID* learn a lot about what an IDE should look 
like from MSVC++ - so give credit where it is due. In many respects GPS 
*EXCEEDS* what I have seen in MSVC++ and does things *better* than 
MSVC++. But it still isn't as fully featured, is it? Hence, it has to 
keep slogging away trying to get better and better so that it can offer 
the developer something he can't get with MSVC++ and create an incentive 
to switch. A really large library with integrated documentation, etc., 
would be a good move in that direction.



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?

Does it matter? The *goal* ought to be to figure out what it is that 
programmers want to buy and give them what they want - or they're going 
somewhere else to get it. Hell. They already have! Do you want to get 
them back? Or get them for the first time? You've got to give them 
something they want or they will continue to stay away by the millions.



> 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,
> 
Never said that simply because it is hyperlinked it is ipso facto 
"Good". What I *said* was good documentation is difficult and time 
consuming to get right, that all-volunteer projects tend to lack much in 
the way of good documentation, that MSVC++ provided some really useful 
stuff in the way of documentation and that MSVC++ had this useful stuff 
hyperlinked via their IDE - and I found that to be useful and cool.

MDC

-- 
======================================================================
Marin David Condic
I work for: http://www.belcan.com/
My project is: http://www.jsf.mil/NSFrames.htm

Send Replies To: m   o   d   c @ a   m   o   g
                    c   n   i       c   .   r

     "So if I understand 'The Matrix Reloaded' correctly, the Matrix is
     basically a Microsoft operating system - it runs for a while and
     then crashes and reboots. By design, no less. Neo is just a
     memory leak that's too hard to fix, so they left him in... The
     users don't complain because they're packed in slush and kept
     sedated"

         --  Marin D. Condic
======================================================================