Examples in Docs, was Re: Escape Sequences in Strings

[peter_richtmyer@my-deja.com]

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/