Re: [9front] 9front man pages

[ori@eigenstate.org]

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