Re: [9front] 9front man pages

[eso@self.rodeo]

Hiro:
> Redoing everything from the ground up is not something we generally
> do here just for the sake of keeping busy
I was not thinking of a ground-up kind of thing. Just a pass-through
with the ideas in my original email in mind.
> Yeah, do we then? How do you know?
I'm sorry for the ambiguity. By "not great" I do not mean "bad" but
just not great, excellent, exceptional. I was talking with 9fans the
day before and I got the feeling that "needs improvement" was an apt
consensus from all those I spoke with. But I apologize for projecting
my narrow slice of perspective on the larger community.
> verbose is a real name, or an attribute?
Both.

Moody:
> This would be touching the artwork for me honestly. I personally love
> some of those more historical examples(Kremvax is my favorite).
I appreciate this perspective. It will not be ignored.

> 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.
My perspective is simply that the purpose of manuals should be to help 
the users.
I don't think you need to redact kremvax or rewrite the docs to do that, 
but in
my opinion there is some room for improvement.

> 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.
I would like that actually, I can do this in supplement to whatever work 
on the
manuals gets done. And having this supplementary resource in mind would 
keep
more examples and explanation out of the man pages, which is something 
others
have expressed concern over.

> 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.
See next quote...

Ori:
> 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.
I'm going to move forward with this. My initial email was trying to get 
some
feedback before I start sending patches, and I've gotten plenty. So I 
will start
sending patches. And I will lose the mentality of a grand effort. Sorry, 
I am
naturally a more idealist head-in-the-clouds kind of person which I 
understand
is inappropriate for this project.

> I think we could use more examples, but I don't think we
> should turn manpages into tutorials.
I agree, that's what I meant by "Usage examples should not be 
exhaustive."
I do value tutorials, but those should stay out of the manuals.

> 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 agree.

Roberto:
> I think there are more important problems with man pages currently,
> like for example some pages that don't give enough context, pages that
> miss important limitations or hidden knowledge, or pages that are 
> clearly
> outdated.
I'm not in the best position to fill in hidden information, but I think 
the
limitations and context are in the same vein as what Ori said above.

qwx:
> just pick manpages you would like to improve, and write a patch,
> so something more specific could be discussed.

Will do. People seem very split on the table of flags vs how it is 
currently.
I'll give others more time to discuss that, and focus on lower hanging 
fruit in
the mean time. Thanks for your messages, and apologies if my formatting 
is crap,
since I'm doing it manually without knowing how wide 80 columns actually 
is on
this email client. Just eyeballing it. Anyways, happy Friday.

verbose