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.9 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,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 C5B1C25E75 for ; Fri, 8 Mar 2024 06:24:53 +0100 (CET) Received: from mimir.eigenstate.org ([206.124.132.107]) by 9front; Fri Mar 8 00:24:00 -0500 2024 Received: from mimir.eigenstate.org (localhost [127.0.0.1]) by mimir.eigenstate.org (OpenSMTPD) with ESMTP id 58c9cbb9 for <9front@9front.org>; Thu, 7 Mar 2024 21:23:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=eigenstate.org; h= message-id:to:subject:date:from:in-reply-to:mime-version :content-type:content-transfer-encoding; s=mail; bh=CnTkMUV86vIF wXPK3nmn4Xv2ZWQ=; b=e5T3+JXccgMghoIezXBxRWHBzisunxvrY9KctcO6FZ4O IPAr6Ie6yJsf+WP1F3akuaJCsA+5Xg3oPInn177tODzgilPpfCLFu/cIGS/LLTjO bOKItXXjxQlZ8WzgwUOO1BufJIY/D47SFh6g11ru2wjdGDjWzHj4CpjLfP/M3LI= DomainKey-Signature: a=rsa-sha1; c=nofws; d=eigenstate.org; h=message-id :to:subject:date:from:in-reply-to:mime-version:content-type :content-transfer-encoding; q=dns; s=mail; b=IvByLSjmeJR9ZEhWnxT Nn3nsRNOT8mJjxTz6MqYsPcnFvzzHEUI2/w+I6x9lD/ipQ49OK7FLtonbF+KNk3K AzIZmAp69s3UP6gG7X134k0jS4X7v4PaVm5F/9uFB3M9ON29YzpymI9l8pPxgb+j NmH8QBc4zuTH2gEnSJ9LCWaY= Received: from abbatoir (pool-108-6-24-2.nycmny.fios.verizon.net [108.6.24.2]) by mimir.eigenstate.org (OpenSMTPD) with ESMTPSA id e003e720 (TLSv1.2:ECDHE-RSA-AES256-SHA:256:NO) for <9front@9front.org>; Thu, 7 Mar 2024 21:23:59 -0800 (PST) Message-ID: <23C3A366562C9ACE92010D2234E3B6D3@eigenstate.org> To: 9front@9front.org Date: Fri, 08 Mar 2024 00:23:57 -0500 From: ori@eigenstate.org In-Reply-To: <682a654116e2456730491ae1f0f0e326@self.rodeo> MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: leveraged rich-client NoSQL YAML over AJAX package-based configuration full-stack optimizer Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk Overall, this sounds reasonable to me (though I'd argue that 9front docs are pretty good, there's certainly room to improve them). 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. Quoth eso@self.rodeo: > 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 disagree. There's room to improve, but I think the system is relatively well docuemnted. It also seems that we do think it's worth our time, but nobody has stepped forward to do a thorough review. If you want to do that, this would be welcome. > 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. I'm assuming by this, you mean a table of flags? I'm in favor of that. > - 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. "typical" varies, but we can discuss on a case by case basis. > - 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 think we could use more examples, but I don't think we should turn manpages into tutorials. > 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 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 attempted something in that style here: https://wiki.9front.org/upas-theory