From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <9front-bounces@9front.inri.net> X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 Received: from 9front.inri.net (9front.inri.net [168.235.81.73]) by inbox.vuxu.org (Postfix) with ESMTP id 7B4A62A5BF for ; Fri, 8 Mar 2024 18:42:54 +0100 (CET) Received: from orthanc.ca ([208.79.93.154]) by 9front; Fri Mar 8 12:40:02 -0500 2024 Received: from orthanc.ca (localhost [127.0.0.1]) by orthanc.ca (OpenSMTPD) with ESMTP id b76ceac3 for <9front@9front.org>; Fri, 8 Mar 2024 09:40:00 -0800 (PST) From: "Lyndon Nerenberg (VE7TFX/VE6BBM)" To: 9front@9front.org In-reply-to: <23C3A366562C9ACE92010D2234E3B6D3@eigenstate.org> References: <23C3A366562C9ACE92010D2234E3B6D3@eigenstate.org> Comments: In-reply-to ori@eigenstate.org message dated "Fri, 08 Mar 2024 00:23:57 -0500." MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <40353.1709919600.1@orthanc.ca> Date: Fri, 08 Mar 2024 09:40:00 -0800 Message-ID: List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: SOAP rich-client rich-client configuration controller Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk My biggest concern with these sort of well meant attempts to help with documentation is this: Writing *good* documentation about a piece of software requires you to have an intimate understanding of that software, down to its core. Without that, you will make mistakes. And quite often what sets apart an amazing manpage from a good one is how it expresses the subtleties of the software it is describing. That requires a deep understanding of the subject matter. For the most part, the Plan 9 manpages are well written as they stand. A few suffer from ESL syndrome and could use some copy editing to remove ambiguity. But a wholesale drive-by edit of everything is wrong, IMO. My major gripe with all the manpages is how the options are documented. I will disagree with Rob Pike until the day I die that they should be described in-line as they currently are. Just like he has red-green colour blindness problems, I suffer from diplopia (very bad double vision) that makes spotting those flag definitions nearly impossible. I firmly believe options should be explicitly called out in a single section in tagged paragraph form (i.e. the idiomatic format used in all the BSD manpages). But that's a bikeshed for another day. In summary, I encourage you to find ways to contribute to the community. If you want to help with documentation, I would start out by picking one or two manpages you feel need an update, then proposing your changes. I suspect you will learn a lot from the ensuing discussion. There is a lot of history behind the style and conventions used; you can't ignore that. --lyndon