Front page | perl.perl5.porters |
Postings from November 2003
Well, i just passed by this one on the list and couldn't resist... On Thu, Nov 27, 2003 at 02:43:47PM +0200, Shlomi Fish wrote: > 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? No, I'm with Alan, please don't dumb down the well written man pages. ;) They are concise, make good logical sense and have a degree of perfection just the way they are. Not that you have a bad idea. If one must "revise", look only to the seemingly infinite expanse of free bits. > Regards, > > Shlomi Fish Allan FieldsThread Previous