Issue 1232073: Links to tutorials and howtos from references (original) (raw)

Issue1232073

Created on 2005-07-04 08:28 by hoffman, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (4)
msg54579 - (view)	Author: Michael Hoffman (hoffman)	Date: 2005-07-04 08:28
I see many people on comp.lang.python who are frustrated by the existing documentation, which is written at an advanced level for total beginners. It might aid in discoverability of the tutorial and howtos if more "See also" links were placed in language and library reference pages. For example: <http://docs.python.org/lib/module-re.html> could link to <http://www.amk.ca/python/howto/regex/>. This would probably reduce the number of basic re questions on c.l.p and tutor, and make it easier to learn the language and stdlib. I'll submit my own patches as I have time.
msg54580 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2005-07-13 21:57
Logged In: YES user_id=80475 -1 The reference docs need to remain loosely coupled or decoupled from the how-tos and tutorial. Links in the other direction are okay (the beginner's guides and overviews may reference the detailed docs). If you're interested in submitting docs patches, it would be nice to get the how-to guides up-to-date.
msg54581 - (view)	Author: Michael Hoffman (hoffman)	Date: 2005-07-13 22:05
Logged In: YES user_id=987664 Why? There are already many links to external documents (including howtos) and even dead-tree books in the reference docs. Try Googling for <site:docs.python.org/lib "see also">. This would definitely be helpful for beginners, and I don't see what the harm is.
msg54582 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2005-07-14 00:35
Logged In: YES user_id=80475 Sorry, I do not think this is a correct solution. Garbaging-up the authoritative references with more links does not make regexps any less challenging. Both the how-tos and tutorial are top level entries in the docs. They are not hidden. Also, users can turn to many other places besides the how-tos and tutorials which are not comprehensive and not unique -- there are tons of beginner guides (on-line and off). There is no doubt that the docs could be improved, but other appoaches need to be taken. There is no straight-forward transformation of what we have now into a guide that can teach people all about programming and how best to use the available tools. For better or worse, that task has been left to third-party guides (Dive into Python, Python & XML, Python in a Nutshell, Python and TkInter, etc). Nothing we can do can easily substitute for any of those. The docs cannot and should not purport to do otherwise.