opinion: comp lang docs style

[rurpy at 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 response to Steven but you like
he is taking "stand on it's own merits" out of context.  The
context I gave was someone who wants a complete and accurate
description of python and who understands programming with
other languages but not python.

> > How many RFCs still in use today don't start with:
> >
>> >> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
>> >> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
>> >> document are to be interpreted as described in RFC 2119

RFC 2119 is incorporated in the others by reference.  It is purely
a matter of technical convenience that those definitions, which are
common to hundreds of RFCs, are factored out to a single common
location.  RFC 2119 is not a tutorial.

> > I posted a response on the article itself, rather than pollute a
> > mailing list with replies to a troll.  The name calling was a rather
> > large hint as to the intention of the "opinion", either that or whoever
> > translated the article (man or machine) was really angry at the time.
> > ;)

I can hint to my neighbor that his stereo is too loud by
throwing a brick through his window.  Neither that nor calling
people arrogant ignoramus is acceptable in polite society.
I am not naive, nor not shocked that c.l.p is not always polite,
and normally would not have even commented on it except that
1) Terry Reedy is usually more polite and thoughtful,
and 2) Xah Lee's post was not a troll -- it was a legitimate
comment on free software documentation (including specifically
python's) and while I don't agree with some of his particulars,
the Python docs would be improved if some of his comments
were considered rather than dismissed with mindless epithets
like troll and arrogant ignoramus.