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 E2AA028664 for ; Fri, 8 Mar 2024 06:10:36 +0100 (CET) Received: from mail.posixcafe.org ([45.76.19.58]) by 9front; Fri Mar 8 00:07:18 -0500 2024 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=posixcafe.org; s=20200506; t=1709874425; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Vij0MF1XnIL8xfxQ+uh2IPFtBlScYr1kVIyuGLaX/fM=; b=vDCXoxohZg8uUayhPF4nAWYd7/5y6nfUKjpwPM0I+k4hpmie4Syau8PudqVvuoaQNSbt02 1lQCGS0YrOXQ0E//49z0BhW0/cTatbFK5jDKPQ/baZ9chn2znETqXS1zGfqNksULY5CmZT BriUGm5Xta/Kijdnkuc3fPQOs+9Br3E= Received: from [192.168.168.200] ( [207.45.82.38]) by mail.posixcafe.org (OpenSMTPD) with ESMTPSA id d76b8b8d (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO) for <9front@9front.org>; Thu, 7 Mar 2024 23:07:05 -0600 (CST) Message-ID: Date: Thu, 7 Mar 2024 23:07:14 -0600 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: 9front@9front.org References: <682a654116e2456730491ae1f0f0e326@self.rodeo> From: Jacob Moody In-Reply-To: <682a654116e2456730491ae1f0f0e326@self.rodeo> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: converged shared descriptor-based CMS self-signing singleton Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk On 3/7/24 22:47, eso@self.rodeo wrote: > I would like to improve 9front's documentation. We all know it's not > great. But those who are in the best position to rewrite them (those > most knowledgeable) see it as not worth their time, which is more than > justified. I am not a computer science professional, I'm just a writer. > Technology is a hobby for me. I cannot write you a filesystem, but maybe > I can write the documentation for it? > I'm willing to try and rewrite the documentation, and I can occasionally > check in with the heavy hitters to see if I'm straight. But first I want > to get some feedback on the objectives of a man page redux. > - Runtime options are listed for readability, like OpenBSD. You > shouldn't have to grep for the most basic information. > - Explanations of software usage should represent a typical 9front user > setup. You could argue that'd be a standalone machine, but I think the > appropriate model would be a local fs+auth server. No more Bell Labs > examples. None of us have that many gateways and nameservers. Nobody has > a gnot terminal. Nobody has a jukebox. And who is emelie? This would be > most relevant to section 8, system administration. > - Usage examples should not be exhaustive, but should cover the most > well-tread paths as far as usage. The first tar(1) man page example > should be extracting a tarball, because that’s what most people use tar > for day-to-day. And if you can imagine a crazy world where you aren't a > powerful technomancer, and thus don't have the tar options memorized, > you could imagine that would be what you'd go looking for in the manual > if you weren't sure. A dd(1) example should be something like cloning > drives, something people often use dd for. This would be touching the artwork for me honestly. I personally love some of those more historical examples(Kremvax is my favorite). I think 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. I am also not sure what you mean by "Runtime options are listed for readability", do you mean to have a table layout for all command line options consistently? If so I also would not personally be a fan of that. > > I'd like to hear what others think. Also I was thinking this would just > cover system usage sections like userland, system administration, file > servers, etc. But if it goes well, maybe we can go beyond that. The last > patch I submitted, for acmed(8), Ori had some objections about my > phrasing. So it seems I could use some advisement. But for the record, I > have experience with technical writing. 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. 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. Just my 2 cents. Thanks, moody