Front page | perl.perl5.porters |
Postings from November 2003
On Thu, 27 Nov 2003, Alan Burlison wrote: > Shlomi Fish wrote: > > > Are you with me? I volunteer to take the initial effort and get this > > effort going. One thing that has to be understood is that the man pages > > should be clear, explanatory, and organized. We cannot leave > > "transliterate" as such because it's a piece of UNIX jargon and not plain > > English. (for example). > > Looks like English to me: > http://dictionary.reference.com/search?r=2&q=transliterate > It is, but what I meant was its meaning deviates from the meaning we mean by the tr/// operator. > I'm all in favour of improving documentation, but I would not like to see > the documents 'dumbed down'. Actually, at the moment, the documentation is quite cryptic and hard to understand and people can have problem understanding it even if they already know the basis of Perl. So, in a way it should be made more clear and idiot-proof. I don't know what you mean by "dumbed down" exactly. > The online manpages are meant primarily as a > reference for people who already know some perl, not as an introductory text > - as you have already said there are plenty of good introductory books that > already cover this ground. > Right, _some_ perl. But let's face it: there are many Perl programmers nowadays who: 1. Are not experienced in any other programming language. 2. Are not native speakers of English. 3. Have little if any experience with UNIX. 4. Just want to find out how to get a job done. Now other technologies such as PHP or Python have adapted their documentation to accomodate with people who are any of the following four. In Perl, the situation is far from being ideal. Many times it's not enough to say what a feature does in one clause, but it is also necessary to explain it for people who are less knowledgable than us, all mighty Perl/UNIX/English/hacking gurus. My friend is one example, and I believe many people are considerably worse than him. Do we agree? Regards, Shlomi Fish > ---------------------------------------------------------------------- Shlomi Fish shlomif@vipe.technion.ac.il Home Page: http://t2.technion.ac.il/~shlomif/ An apple a day will keep a doctor away. Two apples a day will keep two doctors away. Falk FishThread Previous | Thread Next