Feature Requests item #1232073, was opened at 2005-07-04 03:28 Message generated for change (Comment added) made by rhettinger You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=355470&aid=1232073&group_id=5470
Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: Documentation Group: None >Status: Closed >Resolution: Rejected Priority: 5 Submitted By: Michael Hoffman (hoffmanm) Assigned to: Nobody/Anonymous (nobody) Summary: Links to tutorials and howtos from references Initial Comment: 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. ---------------------------------------------------------------------- >Comment By: Raymond Hettinger (rhettinger) Date: 2005-07-13 19:35 Message: 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. ---------------------------------------------------------------------- Comment By: Michael Hoffman (hoffmanm) Date: 2005-07-13 17:05 Message: 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. ---------------------------------------------------------------------- Comment By: Raymond Hettinger (rhettinger) Date: 2005-07-13 16:57 Message: 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. ---------------------------------------------------------------------- You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=355470&aid=1232073&group_id=5470 _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
