On Sun, May 04, 2014 at 07:12:10AM +0200, lu...@proxima.alt.za wrote:
>
> Personally, kernel pages would be a god-send
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
man pages one knows that the ones who wrote the code knew what they were
doing---is difficult. One can have the code done, sort of "working",
without being able to explain to humans exactly why he has done
the things this way or without being able to explain all he had in
mind---things that subconsciously drove the implementation.
I know that now, I start by "explaining" to me what I want to
achieve and critize or "ask" myself the axiomatic, before indeed
starting to implement---after, for the details, it is a dialog between
theory and code. So now the doc and man pages appear first.
Not after. And I'm verifying that the code conforms to what it was
supposed to achieve (it's not as obvious as it may seem).
And there is the problem of the tong. I know that when I tried to
wrote directly into "english", it was a disaster. I have written
the same library---in CWEB that is literate programming; code in
C, explanations formated with TeX---first in english, after in
french, and the result in english was nonsense for the explanations
and code that worked, sort of, but had remote link (hopefully) with
the explanations. Rewriten in french, both explanations and code
improved, simply because I could directly map what I had in mind
in words without trying to first translate i.e. betray (in italian,
they says "tradutore, traditore") and because it was supposed to
be read by me, first, and not to be a public monument to my supposed
smartness, putting things that had nothing to do there instead on
focusing on the task.
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.
I don't think too that the trafic on the list is too high to forbid,
once somebody has something ready for review, to put a link and to
ask for comments.
--
Thierry Laronde <tlaronde +AT+ polynum +dot+ com>
http://www.kergis.com/
http://www.renaissance-francaise.fr/
Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C
