Re: [9fans] ehci/uhci interrupts

[erik quanstrom <quanstro@quanstro.net>]

> Despite what one might think at first, writing documentation is not
> easier than writing code, and is, IMHO, harder. To write good manual
> pages---the Bell Labs man pages are simply great and from reading the

i agree with your points, but i think there are two additional facts to consider.

1.  software is often not intrinsicly hard to write.  the hard bit is the experience
that goes into discovering *what* to write, and which of the many implementation
techniques really wins.

so the skills needed to write the man page differ from the skills needed to
write, and that difference is largely experience, i think you've made an excellent
argument that writing a few man pages is an excellent exercize for anyone,
most especially a gifted student or newcomer to plan 9.

2.  perfection should not be the enemy of good.  if the manual page is
currently missing, a passible man page is better than nothing, so long as
it is humble and doesn't try to explain things that are not properly understood.
which is to say, incomplete is fine, but wrong is not.

> So, IMHO, one embarking in writing manual pages, should start by writing
> in one's native tong taking the Bell Labs man pages as an example. And
> once there is nothing more to remove and the manual page is considered
> good (simplicity is the shortest way to truth), let the translation in
> "C" (pseudo-english) begin.

having lived and worked in a non-english-speaking country, i think this may
vary by individual.  translating back and forth was too much work and too
distracting for me.  additionally, i found the x:y language dictionaries to be
especially inaccurate for technical terms.  in fact, in the professional area i
worked in, to this day, i don't know the field's technical jargon in english.
i never learned it.

an odd thesis that i probablly don't have time to investigate: man pages
are lower vocabulary complexity than natural language, if jargon is set aside.

- erik