I would like to see links to relevant PEP / mailing list docs in the main docs. For example http://docs.python.org/library/dircache.html after "Deprecated since version 2.6" could include a (PEP x.x) link where I could read why it was deprecated and probably what to use in it's place. The docs right now are quite excellent describing the "what" about everything, but often have little to say about the "why". This is a good thing, but links would surely help those that want to learn more. -- Zachary Burns (407)590-4814 Aim - Zac256FL Production Engineer (Digital Overlord) Zindagi Games
Le Mon, 16 Mar 2009 10:25:00 -0700, Zac Burns <zac256@gmail.com> s'exprima ainsi:
I would like to see links to relevant PEP / mailing list docs in the main docs.
+++ PEPs -- with purpose and rationale, and deeply reviewed -- are most often great. There are actually often more legible even for non-specialists, simply because they tell you why. If one doesn't understand the PEP's introduction, then yes, probably this person does not need the feature ;-)
More than true, imo. Every feature documentation could (should?) start answering the infamous "why?"; meaning the purpose, issue,... I really do not agree with the "if you don't know why, you don't need it" (elitist) argument. Denis ------ la vita e estrany
Feel free to send patches, as small as they may seem. Mark up PEP numbers in reST like this -- :pep:`42` -- to get automatic linking. Georg Shawn Ligocki schrieb:
-- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.
Feel free to send patches, as small as they may seem. Mark up PEP numbers in reST like this -- :pep:`42` -- to get automatic linking.
We might want to include a PEP index in the documentation but I think it's a really bad idea to include links from within the docs. The PEPs get out of date quickly. They document an early decision but not its ultimate evolution and diffusion through-out the language. Raymond
On Mon, Mar 16, 2009, Raymond Hettinger wrote:
There are two reasons to link to PEPs: * Provide the historical context * Give detailed info lacking in the docs The first purpose will always exist, and I see no reason to delete such a link if documented as such. Links for the latter purpose can be removed when the docs are updated to match what's available in the PEP. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Adopt A Process -- stop killing all your children!
Le Mon, 16 Mar 2009 16:54:44 -0700, Aahz <aahz@pythoncraft.com> s'exprima ainsi:
Agree with Raymond. It should be made clear along with the pointer that the pointed PEP could be outdated. Maybe simply writing (original PEP: :pep:`42`) is enough? The word 'original' implicitely stating that things could have changed?
To me the most important aspect is not about having details (still, it's important). Instead it is to get an (even partial or obscure) answer to "why", that often simply misses in the official docs. This answer is necessary to interpret the "what" and/or "how". Nobody can properly understand a feature description without knowing its purpose. In the best case, the reader will guess it, in he worst, he will guess wrong. Explicit is better than... also for docs! There is also a pedagogical aspect that I find even more relevant. An unexperienced programmer or pythonist should at least be able to figure out vaguely what this or that feature is about. No doubt this is very difficult to achieve -- especially for experts! I imagine a 2-stage "why" introduction to every feature description in the docs: the first one targeted to non-specialists, the second one more technical. (I'm sure that the first one would also sometimes help specialists.) The pedagogical one must be worded by, or reviewed by, or written in colloboration with, "tutors" that are able to imagine where/how/why newbies may stuck. It needs not beeing long -- sometimes a few words may be enough. (But it will sometimes be the hardest part ;-). It would also benefit from newbie feedback. I wonder whether this task could be partially delegated to the python-tutor mailing list activists. Denis PS: If ever, I volonteer to take part to this kind of task -- for the french version. [Have been technical trainer (in automation) in a previous life.] ------ la vita e estrany
Le Mon, 16 Mar 2009 10:25:00 -0700, Zac Burns <zac256@gmail.com> s'exprima ainsi:
I would like to see links to relevant PEP / mailing list docs in the main docs.
+++ PEPs -- with purpose and rationale, and deeply reviewed -- are most often great. There are actually often more legible even for non-specialists, simply because they tell you why. If one doesn't understand the PEP's introduction, then yes, probably this person does not need the feature ;-)
More than true, imo. Every feature documentation could (should?) start answering the infamous "why?"; meaning the purpose, issue,... I really do not agree with the "if you don't know why, you don't need it" (elitist) argument. Denis ------ la vita e estrany
Feel free to send patches, as small as they may seem. Mark up PEP numbers in reST like this -- :pep:`42` -- to get automatic linking. Georg Shawn Ligocki schrieb:
-- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.
Feel free to send patches, as small as they may seem. Mark up PEP numbers in reST like this -- :pep:`42` -- to get automatic linking.
We might want to include a PEP index in the documentation but I think it's a really bad idea to include links from within the docs. The PEPs get out of date quickly. They document an early decision but not its ultimate evolution and diffusion through-out the language. Raymond
On Mon, Mar 16, 2009, Raymond Hettinger wrote:
There are two reasons to link to PEPs: * Provide the historical context * Give detailed info lacking in the docs The first purpose will always exist, and I see no reason to delete such a link if documented as such. Links for the latter purpose can be removed when the docs are updated to match what's available in the PEP. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Adopt A Process -- stop killing all your children!
Le Mon, 16 Mar 2009 16:54:44 -0700, Aahz <aahz@pythoncraft.com> s'exprima ainsi:
Agree with Raymond. It should be made clear along with the pointer that the pointed PEP could be outdated. Maybe simply writing (original PEP: :pep:`42`) is enough? The word 'original' implicitely stating that things could have changed?
To me the most important aspect is not about having details (still, it's important). Instead it is to get an (even partial or obscure) answer to "why", that often simply misses in the official docs. This answer is necessary to interpret the "what" and/or "how". Nobody can properly understand a feature description without knowing its purpose. In the best case, the reader will guess it, in he worst, he will guess wrong. Explicit is better than... also for docs! There is also a pedagogical aspect that I find even more relevant. An unexperienced programmer or pythonist should at least be able to figure out vaguely what this or that feature is about. No doubt this is very difficult to achieve -- especially for experts! I imagine a 2-stage "why" introduction to every feature description in the docs: the first one targeted to non-specialists, the second one more technical. (I'm sure that the first one would also sometimes help specialists.) The pedagogical one must be worded by, or reviewed by, or written in colloboration with, "tutors" that are able to imagine where/how/why newbies may stuck. It needs not beeing long -- sometimes a few words may be enough. (But it will sometimes be the hardest part ;-). It would also benefit from newbie feedback. I wonder whether this task could be partially delegated to the python-tutor mailing list activists. Denis PS: If ever, I volonteer to take part to this kind of task -- for the french version. [Have been technical trainer (in automation) in a previous life.] ------ la vita e estrany
participants (6)
-
Aahz -
Georg Brandl -
Raymond Hettinger -
Shawn Ligocki -
spir -
Zac Burns