Re: opinion: comp lang docs style

2011-01-06 Thread Xah Lee
On Jan 4, 3:17 pm, "ru...@yahoo.com" wrote: > On 01/04/2011 01:34 PM, Terry Reedy wrote: > > > On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote: > > > what he called > >> a opinion piece. > > > I normally do not respond to trolls, but while expressing his opinions, > > AI made statements that are

Re: opinion: comp lang docs style

2011-01-05 Thread Emile van Sebille
On 1/5/2011 12:10 PM ru...@yahoo.com said... A language reference manual should completely and accurately describe the language it documents. (That seems fairly obvious to me although there will be differing opinions of how precise one needs to be, etc.) Once it meets that minimum standard,

Re: opinion: comp lang docs style

2011-01-05 Thread ru...@yahoo.com
On 01/05/2011 12:23 AM, Alice Bevan–McGregor wrote: > > On 2011-01-04 22:29:31 -0800, Steven D'Aprano said: > > >> >> In any case, your assumption that any one documentation work should stand >> >> on its own merits is nonsense -- *nothing* stands alone. > > > > +1 I responded more fully in my res

Re: opinion: comp lang docs style

2011-01-05 Thread ru...@yahoo.com
On 01/04/2011 11:29 PM, Steven D'Aprano wrote: > On Tue, 04 Jan 2011 15:17:37 -0800, ru...@yahoo.com wrote: > >>> If one wants to critique the 'Python Docs', especially as regards to >>> usefulness to beginners, one must start with the Tutorial; and if one >>> wants to use if statements as an examp

Re: opinion: comp lang docs style

2011-01-04 Thread Alice Bevan–McGregor
On 2011-01-04 22:29:31 -0800, Steven D'Aprano said: In any case, your assumption that any one documentation work should stand on its own merits is nonsense -- *nothing* stands alone. +1 How many RFCs still in use today don't start with: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",

Re: opinion: comp lang docs style

2011-01-04 Thread Steven D'Aprano
On Tue, 04 Jan 2011 15:17:37 -0800, ru...@yahoo.com wrote: >> If one wants to critique the 'Python Docs', especially as regards to >> usefulness to beginners, one must start with the Tutorial; and if one >> wants to use if statements as an example, one must start with the >> above. > > No. The l

Re: opinion: comp lang docs style

2011-01-04 Thread ru...@yahoo.com
On 01/04/2011 01:34 PM, Terry Reedy wrote: > On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote: > > what he called >> a opinion piece. > > I normally do not respond to trolls, but while expressing his opinions, > AI made statements that are factually wrong at least as regards Python > and its practi

Re: opinion: comp lang docs style

2011-01-04 Thread Terry Reedy
On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote: what he called a opinion piece. I normally do not respond to trolls, but while expressing his opinions, AI made statements that are factually wrong at least as regards Python and its practitioners. 1. He correctly notes that the Python Lan

Re: opinion: comp lang docs style

2011-01-04 Thread Google Poster
On Jan 4, 12:24 pm, Xah Lee wrote: > a opinion piece. > > 〈The Idiocy of Computer Language > Docs〉http://xahlee.org/comp/idiocy_of_comp_lang.html > > -- > The Idiocy of Computer Language Docs > > Xah Lee, 2011-01-03 > > Worked with Mathematica for a

Re: opinion: comp lang docs style

2011-01-04 Thread Jason Earl
On Tue, Jan 04 2011, Xah Lee wrote: > a opinion piece. > > 〈The Idiocy of Computer Language Docs〉 > http://xahlee.org/comp/idiocy_of_comp_lang.html > > -- > The Idiocy of Computer Language Docs > > Xah Lee, 2011-01-03 > > Worked with Mathematica for

opinion: comp lang docs style

2011-01-04 Thread Xah Lee
a opinion piece. 〈The Idiocy of Computer Language Docs〉 http://xahlee.org/comp/idiocy_of_comp_lang.html -- The Idiocy of Computer Language Docs Xah Lee, 2011-01-03 Worked with Mathematica for a whole day yesterday, after about 10 years hiatus. Ver