From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 1014db,1042f393323e22da X-Google-Attributes: gid1014db,public X-Google-Thread: 109fba,1042f393323e22da X-Google-Attributes: gid109fba,public X-Google-Thread: 103376,1042f393323e22da X-Google-Attributes: gid103376,public From: Jonathan Guthrie Subject: Re: Any research putting c above ada? Date: 1997/05/15 Message-ID: <5lfibi$4ks$1@news.hal-pc.org> X-Deja-AN: 241772427 Distribution: inet References: <5ih6i9$oct$1@waldorf.csc.calpoly.edu> <5iri6b$jn0@bcrkh13.bnr.ca> <5k60au$gig@bcrkh13.bnr.ca> <5k88f8$387@bcrkh13.bnr.ca> <5ku5tj$9d9$1@goanna.cs.rmit.edu.au> <5AB7287E9247441B.B61EDFD34B8F49B0.FCD25A82E03921C6@library-proxy.airnews.net> <0313A6944836C48E.193DB760B2AB7789.7A79EA9ECF40F6E3@library-proxy.airnews.net> <5ld05e$7tv@news1.mnsinc.com> Organization: Houston Area League of PC Users Newsgroups: comp.lang.c++,comp.lang.c,comp.lang.ada Date: 1997-05-15T00:00:00+00:00 List-Id: In comp.lang.ada Szu-Wen Huang 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.