Re: Any research putting c above ada?

[Jonathan Guthrie <jguthrie@brokersys.com>]

In comp.lang.ada Szu-Wen Huang <huang@mnsinc.com> wrote:

> Here we see two excellent and not mutually contradictory points.  Craig
> is saying that a college student, especially one in CS, should have
> enough initiative to know the relevance of documentation.  I don't
> think Jonathan is actually disagreeing with that, though he makes it
> sound like so by saying the software is to blame.

In my posts in this thread (this makes three, I believe) I have not 
ONCE said anything about the student or his grade on the project.  I
break this trend now.  If I were in the position of the instructor,
I believe that I would probably not give him full credit for the
assignment.  It is, after all the student's responsibility to make
sure that the complete assignment is received by the grader.  In the
real world, you can fail for reasons that aren't anything you have
control over.  This is known as "bad luck," a concept which has
fallen out of favor.

My actual point is twofold.  First, saying "he should have read the
manual" isn't a good thing to do because documenting a bad design does
not make the bad design better.  Second, most technical documentation
is bad which leads to people not being able to use it.  (Either because
they don't read it or because they don't understand it.  Either way,
that is a failure of the documentation.  I've recently come to a fairly
deep respect for good technical documentation.)

> Do we really want to produce CS students who sit on their asses assuming
> that software will warn them of every potential problem?

No, we want to produce CS graduates who write software for people who sit
on their asses...

> : Computer programs need not obey any physical laws so they cannot, except
> : through the effort of the programmer, let the user know what has happend.
> : If the program can't tell the user what's going to happen, at least it
> : should tell the user what has happened.

> All sound principles that I agree with.  However, I'm sure you don't
> actually *expect* all software to be this uniformly good.  I'm sure you
> don't just sit down in front of a new OS and click and drag randomly and
> expect that all damages you make can be undone, right?

Let me tell you about the time I deleted all the /usr/lib/libc* files on
my Linux system...

However, I DO expect all software to be that uniformly good.  I may be
disappointed sometimes, but if I don't expect it, it will never happen.
Programming wants to become a kind of engineering.  For that to happen,
the concept of "acceptable practice" has to be universally understood
and adhered to by its practitioners.

> : Yes, indeed.  Why bother printing them?  I think that the world would
> : be a much better place if programmers didn't use the crutch of "the
> : manual".  ("The fact that it's going to eat all of your tax records
> : and get you sent to jail for the rest of your life if you run it before
> : noon on February 29 is documented on page 879 of the manual.  What?
> : You didn't commit to memory all 12347 pages of the manual?")

> You give some extreme examples.  I believe the more common example is
> the idiot who doesn't read at all and breaks something.

> Ideally all software would be completely intuitive, requiring no manual.
> Is that actually feasible?

I don't think that, in an ideal world, all software would be completely
intuitive.  There is a parable about the instruction book for an ax in
_The Zen of Programming_ that might be enlightening.  In fact, I have
argued that it is impossible for ANY software to be truly "intuitive"
because software need not obey any physical laws.  I am not saying that
manuals should not be printed.  I'm trying to get people to think about
what goes in them.  If I can get people to wonder what a manual is good
for (or, more importantly, what it is NOT good for) then I have made my
point. 

It's not just enough to document serious problems (and anything that
eats data is a serious problem with a computer program) you have to
make the end user aware of the danger and make sure that he understands
it.  This is a tall order, but it's what's required.  (Also note that
I'm not just talking about the documentation of software, but of just
about everything.)

The tendency nowadays is to separate manuals into "reference" and "quick
start" sections.  The point being to reduce the apparent amount of
crud that you have to wade through to make use of the documentation in
the most common cases.  This is a good trend, but it's not nearly finished.
The most common problems seem to be related to circular definitions ("The
widget counter is used to count widgets.") or an assumption that the end
user understands the consequences of the use of a particular feature.

-- 
Jonathan Guthrie (jguthrie@brokersys.com)
Information Broker Systems   +281-895-8101   http://www.brokersys.com/
12703 Veterans Memorial #106, Houston, TX  77014, USA

We sell Internet access and commercial Web space.  We also are general
network consultants in the greater Houston area.