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.6 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, 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 91E0724A18 for ; Fri, 8 Mar 2024 17:03:31 +0100 (CET) Received: from mail-108-mta149.mxroute.com ([136.175.108.149]) by 9front; Fri Mar 8 11:02:06 -0500 2024 Received: from filter006.mxroute.com ([136.175.111.2] filter006.mxroute.com) (Authenticated sender: mN4UYu2MZsgR) by mail-108-mta149.mxroute.com (ZoneMTA) with ESMTPSA id 18e1eccc6490003bea.001 for <9front@9front.org> (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384); Fri, 08 Mar 2024 16:02:00 +0000 X-Zone-Loop: 8aeaa0d02a67b863e7899029a9c0c589d4bd3d53b168 X-Originating-IP: [136.175.111.2] DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=self.rodeo; s=x; h=Content-Transfer-Encoding:Content-Type:Message-ID:References: In-Reply-To:Subject:To:From:Date:MIME-Version:Sender:Reply-To:Cc:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=r+FssfMCv8SdtcJ+7Ao7kocM4xZsX/IM83pewd2ZDXI=; b=iwrAQJ+CbuiOUYj0WQ8RxoKl2o H2H6O1hPPDkLhNkWsMREB9/nw2uPqytdHjziPMR2viYMcE4BdfHN/EpSzu6lQuQt4lR1Qj4AXqc1f TAdFJjFr05pYaz42MJjHaat2Js+C0k6vESt5n9XUFpCzoyGHy735EMHCG50Ziik+uHyI9RavRQLMF 5fuJRUh7o1N0e4e6K+AdTKmRvW6v/YpwThKetCjWAQG6htaFyhsxVVlchJnXKgkXJtQYvu1V6GZMx Vh2auXW7aUPt+j3CB98ak4bm9ICcXqREoubnvibSK2oZGlZ/NEH5to+yvlO83t0zfBJ+onM93+bS5 9zA+fc0w==; MIME-Version: 1.0 Date: Fri, 08 Mar 2024 08:01:58 -0800 From: eso@self.rodeo To: 9front@9front.org In-Reply-To: References: Message-ID: <20f2eb52d0fe7f49534e717415af1f09@self.rodeo> X-Sender: eso@self.rodeo Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit X-Authenticated-Id: eso@self.rodeo List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: lossless non-blocking module-aware map/reduce-aware manager Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk Hiro: > Redoing everything from the ground up is not something we generally > do here just for the sake of keeping busy I was not thinking of a ground-up kind of thing. Just a pass-through with the ideas in my original email in mind. > Yeah, do we then? How do you know? I'm sorry for the ambiguity. By "not great" I do not mean "bad" but just not great, excellent, exceptional. I was talking with 9fans the day before and I got the feeling that "needs improvement" was an apt consensus from all those I spoke with. But I apologize for projecting my narrow slice of perspective on the larger community. > verbose is a real name, or an attribute? Both. Moody: > This would be touching the artwork for me honestly. I personally love > some of those more historical examples(Kremvax is my favorite). I appreciate this perspective. It will not be ignored. > our manual pages overall are pretty great and I don't think the > examples > need to be min-maxed for most common deployment. We're here to have > some > fun as well. My perspective is simply that the purpose of manuals should be to help the users. I don't think you need to redact kremvax or rewrite the docs to do that, but in my opinion there is some room for improvement. > I think what you want would be better suited to something besides the > manual > pages. It sounds like a majority of your grips are with examples. Maybe > you > could make a git repo full of examples, or perhaps something for the > wiki or > the fqa. I would like that actually, I can do this in supplement to whatever work on the manuals gets done. And having this supplementary resource in mind would keep more examples and explanation out of the man pages, which is something others have expressed concern over. > If you feel strongly about some manual page examples I'd say point > those out > specifically and we can discuss specific replacements and examples, but > a more > general "modernize the manpage examples" is going to be hard to agree > to. See next quote... Ori: > I'd just suggest going one manpage at a time, and getting feedback > as you go; you'll probably get a feel for what the docs should be as > we discuss. There's a lot to improve, but I think you'll find there's > a lot we quite like about the current style. I'm going to move forward with this. My initial email was trying to get some feedback before I start sending patches, and I've gotten plenty. So I will start sending patches. And I will lose the mentality of a grand effort. Sorry, I am naturally a more idealist head-in-the-clouds kind of person which I understand is inappropriate for this project. > I think we could use more examples, but I don't think we > should turn manpages into tutorials. I agree, that's what I meant by "Usage examples should not be exhaustive." I do value tutorials, but those should stay out of the manuals. > I think the biggest missing thing in the 9front documentation > is is a set of "theory of operation" type documents that sit > between manpages and the fqa, and walk through how the pieces > of the system are meant to interact. I agree. Roberto: > I think there are more important problems with man pages currently, > like for example some pages that don't give enough context, pages that > miss important limitations or hidden knowledge, or pages that are > clearly > outdated. I'm not in the best position to fill in hidden information, but I think the limitations and context are in the same vein as what Ori said above. qwx: > just pick manpages you would like to improve, and write a patch, > so something more specific could be discussed. Will do. People seem very split on the table of flags vs how it is currently. I'll give others more time to discuss that, and focus on lower hanging fruit in the mean time. Thanks for your messages, and apologies if my formatting is crap, since I'm doing it manually without knowing how wide 80 columns actually is on this email client. Just eyeballing it. Anyways, happy Friday. verbose