From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from minnie.tuhs.org (minnie.tuhs.org [45.79.103.53]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 798f1f76 for ; Thu, 19 Sep 2019 18:44:54 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id CF0A89BC05; Fri, 20 Sep 2019 04:44:52 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 1312D9B906; Fri, 20 Sep 2019 04:44:37 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id C01529B906; Fri, 20 Sep 2019 04:44:35 +1000 (AEST) Received: from darkstar.fourwinds.com (fourwinds.com [63.64.179.162]) by minnie.tuhs.org (Postfix) with ESMTPS id 5851B947B9 for ; Fri, 20 Sep 2019 04:44:35 +1000 (AEST) Received: from darkstar.fourwinds.com (localhost [127.0.0.1]) by darkstar.fourwinds.com (8.15.2/8.15.2) with ESMTP id x8JIiYCP018982 for ; Thu, 19 Sep 2019 11:44:34 -0700 Received: from darkstar.fourwinds.com (jon@localhost) by darkstar.fourwinds.com (8.15.2/8.15.2/Submit) with ESMTP id x8JIiYoP018979 for ; Thu, 19 Sep 2019 11:44:34 -0700 Message-Id: <201909191844.x8JIiYoP018979@darkstar.fourwinds.com> From: Jon Steinhart To: The Eunuchs Hysterical Society In-reply-to: References: <1568916649.17313.for-standards-violators@oclsc.org> Comments: In-reply-to Clem Cole message dated "Thu, 19 Sep 2019 14:37:05 -0400." MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-ID: <18977.1568918674.1@darkstar.fourwinds.com> Content-Transfer-Encoding: 8bit Date: Thu, 19 Sep 2019 11:44:34 -0700 X-JON-SPAM: local delivery Subject: Re: [TUHS] earliest Unix roff X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: The Unix Heritage Society mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" Clem Cole writes: > > On Thu, Sep 19, 2019 at 2:11 PM Norman Wilson wrote: > > > Manual entries, as printed by man and once upon a time in > > the Programmers' Manual Volume 1, should be concise references. > > They are not a place for tutorials or long-winded descriptions > > or even long lists of hundreds of options (let alone descriptions > > of why the developer thinks this is the neatest thing since > > sliced bread and what bread he had in his sandwiches that day). > > > > For many programs, one or two pages of concise reference is > > all the documentation that's needed; no one needs a ten-page > > tutorial on how to use cat or rm or ls, for example. But some > > programs really do deserve a longer treatment, either a tutorial > > or an extended reference with more detail or both. Those belong > > in separate documents, and are why the Programmers' Manual had > > a second volume. > > > > Nowadays people think nothing of writing 68-page-long manual > > entries (real example from something I'm working with right now) > > that are long, chatty lists of options or configuration-file > > directives with tutorial information interspersed. The result > > makes the developer feel good--look at all the documentation > > I've written!!--but it's useless for someone trying to figure > > out how to write a configuration file for the first time, and > > not so great even for someone trying to edit an existing one. > > > > Even the Research system didn't always get this right; some > > manual entries ran on and on and on when what was really > > needed was a concise list of something and a longer accompanying > > document. (The Tenth Edition manual was much better about > > that, mostly because of all the work Doug put in. I doubt > > there has ever been a better editor for technical text than > > Doug.) But it's far worse now in most systems, because > > there's rarely any editor at all; the manuals are just an > > accreted clump. > > > > And that's a shame, though I have no suggestions on how > > to fix it. > > > > +1 This is sort of my late in life mission. Here's a description of a session that I've proposed for an upcoming conference. Once upon a time there was Budweiser. Then, along came craft beer which started a movement. Now, one can find a whole range of offerings from craft cheese to artisanal baking soda. Hard to find is craft programming. What’s called "programming technology" today seems to be the art of minimizing the damage that can be done by monkeys at keyboards. Since we can no longer purchase even a toothpick that doesn’t contain a processor and a blue LED, we depend on code. How can we revive the art of programming? How do we foster the creation of good code instead of spending energy minimizing the damage that can be done by bad code? Our lives depend on it. My two cents is that craft programmers know how to write good documentation. Probably one of the things that made BTL so wonderful was the breadth of knowledge that people had. Ken was recently telling me about Lee McMahon who was a classically trained monk in addition to writing qsort for V3.