Path: utzoo!utgpu!news-server.csri.toronto.edu!qucdn!spraggej
Organization: Queen's University at Kingston
Date: Wednesday, 17 Apr 1991 17:51:06 EDT
From: John G. Spragge <SPRAGGEJ@QUCDN.QueensU.CA>
Message-ID: <91107.175106SPRAGGEJ@QUCDN.QueensU.CA>
Newsgroups: comp.lang.pascal
Subject: Re: Borland flaming
References:  <memo.928064@lynx.northeastern.edu>

In article <memo.928064@lynx.northeastern.edu>, cschmidt@lynx.northeastern.edu
says:

>My Turbo Pascal 5.0 update devotes just one sentence to describing the
>differences between the 4.0 and 5.0 runtime libraries.  Here is that
>sentence in full:
>
>> A number of procedures and functions have been added or modified;
>> they're detailed in Chapter 16 of the Reference Guide, "Turbo Pascal
>> Reference Lookup".
>
>This suggests that we should read all of chapter 16, nearly 200 pages,
>in an attempt to spot changes to runtime library routines that might
>cause our 4.0 programs to work incorrectly.  This attempt would have
>been futile, of course.  One wonders whether Borland thinks anyone is
>actually using their compiler.  When I upgraded to 5.0, I already had
>about 100,000 lines of carefully debugged 4.0 code, so you can imagine
>how angry I felt when confronted with Borland's attitude about
>documenting revisions.

First off, I don't recall the transition to Turbo 5 breaking ANY of
my code, and I had several big projects on the go at the time. Second,
your TP4 units had to be recompiled anyway; presumably any major
changes would have caused a syntax error, in which case you could
have looked up the routine involved. As I recall, however, the
libraries were pretty compatible, so that there was only one line
of documentation for the good reason that there wasn't much to
document.

  [ list of specific information not included in the manuals ]
  [ omitted.                                                 ]

>          I belive the answers to these and other questions would
>stand a better chance of finding their way into the manual if Borland
>discontinued its preoccupation with writing long tutorials and
>defining rules only by inference in the form of examples.

Borland manuals are a balance of tutorials for new users and a
pretty good set of reference manuals.

>This is all just my opinion of course.  Maybe I am wrong.  Maybe
>computer documentation is generally a lot better than I think it is.
>Ask your clients and colleagues what they think.

None of my clients or colleagues like the same documentation at
the same time. Computer documentation isn't BETTER than you think;
it's HARDER than you think. That's why flaming writers who don't
put exactly the answer you want in their manuals is not useful.
They can't put in the answer to every conceivable question: the
manuals would weigh several tons and be impossible to read.

disclaimer: Queen's University supplies me with computer services, not
            my opinions.

John G. Spragge