9front - general discussion about 9front
 help / color / mirror / Atom feed
From: eso@self.rodeo
To: 9front@9front.org
Subject: [9front] 9front man pages
Date: Thu, 07 Mar 2024 20:47:12 -0800	[thread overview]
Message-ID: <682a654116e2456730491ae1f0f0e326@self.rodeo> (raw)

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

             reply	other threads:[~2024-03-08  4:48 UTC|newest]

Thread overview: 21+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-03-08  4:47 eso [this message]
2024-03-08  5:07 ` Jacob Moody
2024-03-08  5:28   ` Roberto E. Vargas Caballero
2024-03-08  9:01     ` qwx
2024-03-08 11:30       ` hiro
2024-03-08 11:34         ` hiro
2024-03-08 11:35           ` hiro
2024-03-08 16:01           ` eso
2024-03-08 16:24             ` qwx
2024-03-08  5:23 ` ori
2024-03-08 17:40   ` Lyndon Nerenberg (VE7TFX/VE6BBM)
2024-03-08 18:30     ` hiro
2024-03-08 23:20       ` umbraticus
2024-03-08 23:50         ` ori
2024-03-09  0:40           ` sl
2024-03-09  1:08             ` hiro
2024-03-09  1:36               ` Stanley Lieber
2024-03-09 11:01                 ` sirjofri
2024-03-10 19:16                   ` Lyndon Nerenberg (VE7TFX/VE6BBM)
2024-03-10 21:05                     ` sirjofri
2024-03-10 21:11                     ` hiro

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=682a654116e2456730491ae1f0f0e326@self.rodeo \
    --to=eso@self.rodeo \
    --cc=9front@9front.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).