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 952fd9bd for ; Mon, 19 Nov 2018 17:06:18 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 7DEA7945F5; Tue, 20 Nov 2018 03:06:17 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 70FDD940FA; Tue, 20 Nov 2018 03:06:06 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 86C7D940FA; Tue, 20 Nov 2018 03:06:05 +1000 (AEST) Received: from darkstar.fourwinds.com (fourwinds.com [63.64.179.162]) by minnie.tuhs.org (Postfix) with ESMTPS id 3CEAB940F8 for ; Tue, 20 Nov 2018 03:06:05 +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 wAJH6422007540 for ; Mon, 19 Nov 2018 09:06:04 -0800 Received: from darkstar.fourwinds.com (jon@localhost) by darkstar.fourwinds.com (8.15.2/8.15.2/Submit) with ESMTP id wAJH64eZ007537 for ; Mon, 19 Nov 2018 09:06:04 -0800 Message-Id: <201811191706.wAJH64eZ007537@darkstar.fourwinds.com> From: Jon Steinhart To: The Eunuchs Hysterical Society In-reply-to: <7171EAB7-9557-4822-8FCE-5C7B1AD19B06@kdbarto.org> References: <201811160003.wAG03mlF139232@tahoe.cs.Dartmouth.EDU> <20181116045016.GK3341@mcvoy.com> <7a632484-cdc7-7c59-7077-7a2c752045da@spamtrap.tnetconsulting.net> <4c36b2b2-76df-435f-27bc-e1feb0647f36@case.edu> <201811162113.wAGLDGiQ031455@darkstar.fourwinds.com> <201811190311.wAJ3BDHR028154@darkstar.fourwinds.com> <7171EAB7-9557-4822-8FCE-5C7B1AD19B06@kdbarto.org> Comments: In-reply-to David message dated "Mon, 19 Nov 2018 07:41:23 -0800." MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-ID: <7535.1542647164.1@darkstar.fourwinds.com> Content-Transfer-Encoding: 8bit Date: Mon, 19 Nov 2018 09:06:04 -0800 X-JON-SPAM: local delivery Subject: Re: [TUHS] man-page style X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.20 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" David writes: > The problem, as we have all converged on, is that writing well is hard. Writing > concise, targeted prose, is even harder. So we get bloat in man pages or the > info system which is just (IMHO) more bloat because people don’t want to spend > the time writing well. I'm going to be a bit contrary here. Yes, writing is hard, but not that hard. Designing is what's harder. I'm gonna make the claim that a lot of projects today aren't designed. They're implemented, and when someone gets something that sort of works they write down a few notes about what was hard for them (if we're lucky) and passes that off as documentation. We're in an era in which it is so easy to just try things that many don't bother which what I'd call design. No surprise that "documentation" from "undesigned" isn't good.