From mboxrd@z Thu Jan 1 00:00:00 1970 Date: Sun, 4 May 2014 12:41:27 +0200 From: tlaronde@polynum.com To: Fans of the OS Plan 9 from Bell Labs <9fans@9fans.net> Message-ID: <20140504104127.GB415@polynum.com> References: <659b566a0bf4993ee7360622c493fb21@brasstown.quanstro.net> Mime-Version: 1.0 In-Reply-To: User-Agent: Mutt/1.4.2.3i Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Subject: Re: [9fans] ehci/uhci interrupts Topicbox-Message-UUID: dd951f32-ead8-11e9-9d60-3106f5b1d025 On Sun, May 04, 2014 at 07:12:10AM +0200, lucio@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 http://www.kergis.com/ http://www.renaissance-francaise.fr/ Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C