From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,88ed72d98e6b3457 X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2003-11-02 11:25:46 PST Path: archiver1.google.com!news2.google.com!news.maxwell.syr.edu!elnk-pas-nf1!newsfeed.earthlink.net!stamper.news.pas.earthlink.net!stamper.news.atl.earthlink.net!newsread1.news.atl.earthlink.net.POSTED!d9c68f36!not-for-mail Message-ID: <3FA55A2E.2050400@noplace.com> From: Marin David Condic User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.0.1) Gecko/20020823 Netscape/7.0 (OEM-HPQ-PRS1C03) X-Accept-Language: en-us, en MIME-Version: 1.0 Newsgroups: comp.lang.ada Subject: Re: Standard Library Interest? (The Big Player ACT) References: <3F82F527.3020101@noplace.com> <3F9EFDC6.7050508@noplace.com> <254c16a.0310290635.1a8b09d2@posting.google.com> <3FA04E6E.2070000@noplace.com> <3FA322D8.2040003@noplace.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Date: Sun, 02 Nov 2003 19:25:45 GMT NNTP-Posting-Host: 209.165.22.181 X-Complaints-To: abuse@earthlink.net X-Trace: newsread1.news.atl.earthlink.net 1067801145 209.165.22.181 (Sun, 02 Nov 2003 11:25:45 PST) NNTP-Posting-Date: Sun, 02 Nov 2003 11:25:45 PST Organization: EarthLink Inc. -- http://www.EarthLink.net Xref: archiver1.google.com comp.lang.ada:1933 Date: 2003-11-02T19:25:45+00:00 List-Id: 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 ======================================================================