Links to tutorials and howtos from references

[hoffman]

BPO	1232073
Nosy	@rhettinger

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2005-07-14.00:35:24.000>
created_at = <Date 2005-07-04.08:28:32.000>
labels = ['type-feature', 'docs']
title = 'Links to tutorials and howtos from references'
updated_at = <Date 2005-07-14.00:35:24.000>
user = 'https://bugs.python.org/hoffman'

bugs.python.org fields:

activity = <Date 2005-07-14.00:35:24.000>
actor = 'rhettinger'
assignee = 'none'
closed = True
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2005-07-04.08:28:32.000>
creator = 'hoffman'
dependencies = []
files = []
hgrepos = []
issue_num = 1232073
keywords = []
message_count = 4.0
messages = ['54579', '54580', '54581', '54582']
nosy_count = 2.0
nosy_names = ['rhettinger', 'hoffman']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue1232073'
versions = []

[hoffman]

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.

[rhettinger]

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.

[hoffman]

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.

[rhettinger]

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.