Re: [9front] 9front man pages

[Jacob Moody <moody@posixcafe.org>]

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