RE: Examples in Docs

["Robert C. Leif, Ph.D." <rleif@rleif.com>]

From: Bob Leif
To: Peter Richtmyer et al.
I believe that you have two subjects intertwined. Since the Ada Reference
Manual is an official document, for purposes of correctness and maintenance,
it should be kept as small as possible. However, when it serves as a
teaching document (using teaching in a broad sense), the user would benefit
from examples. Since many of us make use of the HTML version, it should be
possible to add hypertext linkages to jump to examples in this derived
document. The hypertext document should include a disclaimer and each
example could have a short disclaimer stating that the example(s) are not
part of the official Reference Manual. I hope this will be a useful
compromise or work-around.

-----Original Message-----
From: comp.lang.ada-admin@ada.eu.org
[mailto:comp.lang.ada-admin@ada.eu.org]On Behalf Of
peter_richtmyer@my-deja.com
Sent: Monday, January 15, 2001 7:31 PM
To: comp.lang.ada@ada.eu.org
Subject: Examples in Docs, was Re: Escape Sequences in Strings


Robert Dewar said:

> Note: for my own taste, I hate to present-by-
example, and I
> hate examples, but my experience is most people
like examples.
> For instance, most people want MORE examples in
the RM, I
> regard them as irritating redundant (well
hopefully redundant)
> non-normative junk :-)

This statement surprised me a little at first. I
always enjoy reading your comments (Unless you
are *bashing* one of my comments.)  :-)

I have saved a comment of yours where you said
that you *liked* to document code, and encourage
others to do so. You said that, if you do it
enough, you can get to enjoy it (or words to that
effect.) Putting examples in documents is
somewhat similar to putting comments in code. It
is not necessary, but it sure makes it easier for
the readers.

But then, I have written documents that I thought
were pretty clear, only to find that others
needed examples to understand them. And yet I am
like those people. I like good examples in the
documents and *good* comments in the code. In
either code or documents, the author (almost)
always knows what he is saying. But code and
documents should be written for the reader.
(Yes, I know that that is not an original thought
on my part). :-)

(Of course, code is written for the compiler
too) :-)

My best regards,
Peter


Sent via Deja.com
http://www.deja.com/