> 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
