Raymond Hettinger added the comment:
Fred, do you want to opine on this?
In some cases, like heapq.py, the personal touch is an essential and beautiful
part of the presentation and is a cherished part of Python. In other cases, it
seems unnecessary or a little off-putting, so perhaps a few changes are
warranted.
Personally, I've grown to really dislike the incessant stream of proposals to
make broad sweeping trivial changes across the code or documentation to fix
made-up problems (ones not reported or cared about by actual users). In
particular, I worry about sending some new dev on a mission to rewrite
documentation that was written by domain experts (Alex Martelli reported that
copy-editors "wreaked havoc" on one of his books just prior to publication by
subtly changing the meaning or correctness of his prose while applying grammar
rules and minor style edits -- I wish to avoid the same for us).
Also, I place high value on text written by Guido and think we lose something
every time someone wants to rewrite it to fit their personal tastes and views
of the language. The tastes and views of module authors are more important are
easily lost in style edits (especially those that change point of view, mood,
or theme of presentation).
Another thought is that there should be different general rules for different
sections. The standard library docs tend to be more formal. The language
reference tends to be even more formal ("for language lawyers"). The tutorial
tends to be personable. The how-to guides are often have a personal touch and
are the only places where we attribute authorship back individuals (actual
by-lines at the top of the file).
[Cheryl Sabella]
> Would it be OK for me to tackle this?
You could, but I would really like to get you involved in more substantive work
that involves thinking about real issues and real code. IMO, this project
isn't worthy of you time and is not on the critical path to your stated goals.
That said, feel free to volunteer for anything that interests you.
----------
assignee: docs@python -> fdrake
nosy: +fdrake, rhettinger
versions: +Python 3.7 -Python 2.7, Python 3.3, Python 3.4
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue18280>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
