Readability of manual (was Re: Top 10 Ada myths)

[dan@cs.uq.oz.au (Dan Johnston D.B.)]

In <EACHUS.95Mar23115217@spectre.mitre.org> eachus@spectre.mitre.org (Robert I. Eachus) writes:

>     In Ada 95, the approach is different.  Tucker did a very good job
>of putting all the rules in the RM, and much of the elaboration needed
>to understand the rules in the annotated version.  As a result, the RM
>is somewhat less readable than in 1983, but those who do read it come
>away with many fewer misconceptions.  Since the rationale is not only
>very readable, maintained and printed in parallel, I think that the
>net effect of the 95 approach is a major improvement.

It appears to me (as a reader only) that there is a difference in the
intended audience.
  The Ada 83 manual seemed to be directed towards the programmer, whereas
  the Ada 95 manual seems to be directed towards compiler writers and
tool developers.
   I found the Ada 83 manual quite readable. When programming, if I had
doubts I could generally go to the manual and find what I wanted. (This was
helped, I believe, by the fact that the compilers I used generally reported
the number of the reference manual clause in the error messages.)  On the
other hand, with the Ada-95 manual, I find it very difficult to find (and
then understand) the rules.  The gnat error messages are generally good
but they don't help find the relevent rules in the manual.
   I don't believe that either the rationale or a text book is a substitute
for a good manual.  Perhaps if I could get a copy of the annotated manual
it might help. (I have ftp'd it but unfortunately it is too large to print
on our system.)  I know that a lot of programmers like to learn from
examples but I don't find that adequate by itself and like to see the rules.
  I know my brain has slowed down in the intervening 10+ years but I would
have hoped that a good knowledge of Ada-83 would have compensated for that
in trying to read the Ada-95 manual.
  Perhaps the origins of Ada-83 in the competitive design process (Green vs
Red etc) was an influence in making its manual more readable.
     dan.      Dan Johnston, Dept of Comp Sci, Uni of Queensland, Australia.
                    dan@cs.uq.oz.au