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 97FD528CA3
	for <ml@inbox.vuxu.org>; Fri,  8 Mar 2024 05:48:27 +0100 (CET)
Received: from mail-108-mta126.mxroute.com ([136.175.108.126]) by 9front; Thu Mar  7 23:47:18 -0500 2024
Received: from filter006.mxroute.com ([136.175.111.2] filter006.mxroute.com)
 (Authenticated sender: mN4UYu2MZsgR)
 by mail-108-mta126.mxroute.com (ZoneMTA) with ESMTPSA id 18e1c6301140003bea.001
 for <9front@9front.org>
 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384);
 Fri, 08 Mar 2024 04:47:14 +0000
X-Zone-Loop: 5bb874f17b42e8d9c363a176d236d1bc76e61d6a9e13
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: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:In-Reply-To:
	References:List-Id:List-Help:List-Unsubscribe:List-Subscribe:List-Post:
	List-Owner:List-Archive; bh=x5N+Ot03IfY6GZRayRRy1DbU4t41nD+4e2tNepaRprA=; b=D
	4WqFS/70BCiyPwoFwLCuajzrNIgO/IR3jKvhJnBWwOiBPuOGfPTmY3awcqhbKttuYtRgb1bWE9eYU
	OskOyGveMTPYuznd5EDUApgJkLBibcY6HwTcxzxRbhFnAoOmNf6k+mq4mDuvtPHeM3lwrx9rfhyXC
	dkMfTx1sJEXPO9beVr95hZr75dAFL+Sf92bhf7jqdoGaIuGXFjOlUBHYWDnEvTUFWsZb7iELCEpSe
	dSYbnZ2zp4B1RQlpGmR9sdk4Jju2lJmGyvwiyCLrFD8+PqB371zUixWdtjwyVasd6ayQvE1abaZnV
	exzFstsLImqqP1E7SxgQ5ofT+JUGwFAOA==;
MIME-Version: 1.0
Date: Thu, 07 Mar 2024 20:47:12 -0800
From: eso@self.rodeo
To: 9front@9front.org
Message-ID: <682a654116e2456730491ae1f0f0e326@self.rodeo>
X-Sender: eso@self.rodeo
Content-Type: text/plain; charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 8bit
X-Authenticated-Id: eso@self.rodeo
List-ID: <9front.9front.org>
List-Help: <http://lists.9front.org>
X-Glyph: ➈
X-Bullshit: stable responsive metadata optimizer 
Subject: [9front] 9front man pages
Reply-To: 9front@9front.org
Precedence: bulk

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.

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.

My Best,

Verbose