Re: [9front] 9front man pages

["Lyndon Nerenberg (VE7TFX/VE6BBM)" <lyndon@orthanc.ca>]

My biggest concern with these sort of well meant attempts to help
with documentation is this:

  Writing *good* documentation about a piece of software
  requires you to have an intimate understanding of that
  software, down to its core.

Without that, you will make mistakes.  And quite often what sets
apart an amazing manpage from a good one is how it expresses the
subtleties of the software it is describing.  That requires a deep
understanding of the subject matter.

For the most part, the Plan 9 manpages are well written as they
stand.  A few suffer from ESL syndrome and could use some copy
editing to remove ambiguity.  But a wholesale drive-by edit of
everything is wrong, IMO.

My major gripe with all the manpages is how the options are documented.
I will disagree with Rob Pike until the day I die that they should
be described in-line as they currently are.  Just like he has
red-green colour blindness problems, I suffer from diplopia (very
bad double vision) that makes spotting those flag definitions nearly
impossible.  I firmly believe options should be explicitly called
out in a single section in tagged paragraph form (i.e. the idiomatic
format used in all the BSD manpages).  But that's a bikeshed for
another day.

In summary, I encourage you to find ways to contribute to the
community.  If you want to help with documentation, I would start
out by picking one or two manpages you feel need an update, then
proposing your changes.  I suspect you will learn a lot from the
ensuing discussion.  There is a lot of history behind the style and
conventions used; you can't ignore that.

--lyndon