Re: Book REview

[ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe)]

mfeldman@seas.gwu.edu (Michael Feldman) writes:
in reply to my review of new Feldman/Koffman book.

Thank God you took it so well.  After Robert Dewar's posting,
I was thinking "oh no, have I made a faux pas? have I offended
all the people I admire in comp.lang.ada?".  WHEW!

>Well, from the list below [snipped to save bandwidth], you've caught
>a helluva lot of typos and a few "cultural errors" that seem to imposed
>an American bias on some of the discussion.

>These typos, and other reported ones, will be fixed at reprint time.

Great!  I had a face-to-face discussion recently with someone about C
textbooks (see my posting "Textbooks!" in comp.lang.c.moderated for
the context) and their comment was "Even K&R make mistakes, but they
_admit_ them and _fix_ them." and that is all one can reasonably expect.

>Whether the "cultural bias" stuff can be repaired remains to be seen.

If you think I'm picky about that, try a Frenchman!

>It is true that this stuff escaped both the reviewers (all profs like
>yourself) and the proofreaders.

As I think I may have mentioned, I am teaching a software engineering
subject, as well as some computer science subjects.  So these days I find
myself thinking,
    what is there about the (book production) PROCESS
    which
	- caused these defects
	- let them through into the product.

Cultural bias.

    A teacher, located in a particular culture, teaching students
    who are immersed in that culture, will naturally try to pick
    examples that involve concepts his students already understand.
    [I was once trying to explain Montague Grammar to a class, and
    said "slash categories are just like the types in typed lambda
    calculus", only to find that they didn't even know what the
    untyped lambda calculus was.  A _good_ teacher doesn't do that!]

    I _suspect_ that the problem is that when course materials that
    have worked well in such a context are turned into a book that
    is to be sold in an international market, "internationalisation"
    is given a low priority compared with topics, presentation, and
    accuracy.

    Perhaps it should be.  However, an Addison-Wesley book I recently
    was sent listed 11 publisher's people by role and name at the top
    of the first page, from "Aquisitions Editor" to "Cover Illustration".
    It is the _publisher_ that has the experience with international
    markets; perhaps amongst all these people, room could be found for
    an "Internationalisation Proofreader".

    Topics to watch out for include
	- references to currency
	- references to political figures (who are Kennet and Brumby?)
	- references to political institutions (what is the ATSIC?)
	- references to the educational system (which is the honours year?)
	- presentation of dates and times (why not follow ISO 8601?)
	- traffic directions and signs (there is an international standard
	  for traffic signs, I believe; some countries still haven't switched)
	  (I never knew why US people talked about "yellow"; our traffic
	  lights are red, ORANGE, and green, plus red and white T signs for
	  the trams)
	- references to local history (what was the Eureka stockade?)
	- references to national sports (what is AFL? how does it differ
	  from VFL? who are the Bombers? how do you play two-up?)
	- it is fair to use national spelling and punctuation in the running
	  text, but examples should not depend on things that differ.
	  (E.g. US punctuation alternates ` ' with `` '', while UK
	  punctuation alternates `` '' with ` '.  No text processing example
	  should rely on either.)
    and there are many others, such as use of colour, iconic symbols, and
    so on.  

    I do not think it is fair to expect every author to be aware of all the
    internationalisation issues.  I have left out some that I do know about,
    and there must be many more that I don't.  I _do_ think that it is fair
    to expect an international publisher selling educational textbooks into
    an international market to have a "Guide for Authors" that mentions
    such issues, and for their proofreaders and copy editors to keep an eye
    out for them.

    Could you perhaps find out whether Addison-Wesley would be interested
    in having something about this in their Guide for Authors?  I would be
    interested in contributing to it.

Incomplete revision

    The book is a large book, (page numbers run up to 814), worked on by
    two authors, who were presumably under pressure to get it out in
    time for the second half of the current academic year.  (See previous
    section...)

    Even Homer nods.  These things happen.  But...

    Is there no hope of having automatic tools to catch some of them?
    Take the Simple_Dates -vs- SimpleDates -vs- Dates issue.
    Simply checking each identifier that appears in the text against
    the index would have caught at least one of these:  Dates and
    Simple_Dates appear in the index, but SimpleDates doesn't.
    It should be possible to automatic this check.

    I would go further.  I would have liked to see packages, procedures,
    and concepts in _separate_ indices, rather like Common Lisp, the
    Language, 2nd edition.

    It should be possible to devise "semantic markup" conventions and
    tools to catch many errors of this type.  For example, if this
    book were in SGML, it would be possible using our SIM system to
    pose queries that take into account the structure of the text,
    "List the names of packages defined in chapter 8"
    "Find all package names used in a chunk preceding the chunk where
    they are defined."
    And so on.

    Even then, the bottom line is the proof reading done by the authors
    and by the publishers.  Now, it took me about 3 hours per chapter,
    and I didn't quite finish chapter 8.  Chapter 14 was 42 pages, so
    that's about 14 pages per hour.  Call it 15.  810/15 = (30*27)/(30*0.5)
    = 54 hours to proof-read the lot, round it up and say 60 hours.
    That's a lot of time, and clearly the authors cannot fully proof-read
    the book after each change.  The retail price isn't quite legible on
    the forms I was sent, but it seems to be around AUD 50.  My time is
    worth (according to the prices the department is actually paid when
    I do consulting) AUD 100 per hour and up.  So the price for a good
    proof-reader to check the book with reasonable care is around the
    AUD 6000 mark, which corresponds to the retail price of 120 copies.
    We have more than that many students in our CS1 class, in fact
    roughly twice that many, and they _won't_ be buying that book until
    the reprint because it _wasn't_ proofread to this level.

    Let's be frank about this:  I _mind_ about the cultural issues, but
    we wouldn't let that stop us buying the book.  The problem is that
    having found a certain number of errors, we don't _know_ whether the
    other errors are serious or not without spending AUD 6000 worth of
    my time.

    This is a book that, if thoroughly proof-read, deserves to sell
    a great many copies.  I think Addison-Wesley should have spent the
    money on first-rate proof-reading.  (Which, by the way, means
    proof-reading by someone reasonably knowledgeable about Ada.  Or,
    if the book is about C, HPF Fortran, or Visual Basic, about C,
    HPF Fortran, or Visual Basic.)  They would have made it back in
    sales at a single site.

Another issue that I didn't really address before.

    CS 1 students, by definition, do not have a wide computing background.
    They do not know what is true of computers in general.
    They only know what they were told in secondary education (*sigh*; I
    wish the high schools would either *stop* teaching computing or
    start doing it right; what I really really long for is students who can
    spell and add; we can teach them the rest) and what they are told in
    their CS1 class.  We should not teach them as universal truths things
    that are truths about a specific language.  This doesn't mean going
    into a lot of detail.  It just means that instead of "You can't do X"
    or "A computer can't do X" one says "You can't express X directly _in
    Ada_."

    If they are told that arrays cannot grow because that is in the nature
    of arrays, they don't know that it isn't true in Burroughs Algol,
    Algol 68, Common Lisp (array-push-extend), Dijkstra's notation (which
    I implemented in Pop; it's _easy_), or a raft of other languages.

    If they are told that records cannot be added because the computer
    can't do it, they don't know that COBOL programmers have been doing
    it for years.

    If they are told that a computer can only operate on single numbers,
    they don't know about complex numbers in Fortran, Pascal, Algol 68,
    or C++, nor does the book mention Ada.Numerics.Complex_Types (which
    it shouldn't, but the message _is_ false about Ada).

    If they are told that "memory cell" = smallest addressible unit = byte
    (yes, yes, I know we're told a memory cell is a _group_ of bytes, but
    the same page tells us that 1 megabyte = 1 million cells) and that
    "a memory cell can contain a program instruction", they probably don't
    know that a SPARC instruction _can't_ fit in a "memory cell" so defined.

    If they are told (on p95) that
	Pi: constant Float := 3.14159;
    many students these days have a sufficiently weak grasp of mathematics
    to believe that Pi = 3.14159.  I wish I were joking.  If Robert Dewar
    is right and students only look at the diskette copies of things, they
    will never notice the definition of p782.  What a pity they weren't
    advised to do

	Pi: constant Float := Ada.Numerics.Pi;

    After all, Float _could_ be more than 32 bits...

>I am creating an errata sheet and will put it online in a short while.

This is excellent news.  Could you please set it up as a form so that
people can easily contribute new problem reports?

>I take full credit for the errors as well as the good stuff. I've gotten
>into the habit of paying students $1.00 for the first report of each 
>error. Be sure that I will scour your list carefully; where do I send
>the check?:-)

I prefer Knuth's offer of $2.56 (:-).
If my comments prove of any use, just tell Addison-Wesley they
want me to review more of their books _before_ they fill the warehouses.

>>Another cultural matter:  what the heck is a GPA?

>US bias. Grade Point Average.:-)

I'm sorry, but that isn't an explanation.  I _have_ received an explanation,
and what a curiosity the thing is.  How come the Statistics department in
every US university hasn't threatened to walk out in a body until something
a little less quirky is adopted?  The explanation belongs in the book.

>>The pity of it all is that my _overall impression_ is that this is a
>>really good book.  If this were a _draft_ I had been sent for review,
>>I would be saying "wonderful, let's use it next year".  Thanks to the
>>sloppy proof-reading, I'm actually saying "I _wish_ we could use this
>>book but we cannot in good conscience recommend it to students without
>>an errata booklet."

>When do you need that errata booklet?

Academic years and civil years coincide in Australia and New Zealand.
We'll be making our decisions about CS1 textbooks in about 4--6 months.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.