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
next 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).