classification
Title: multiprocessing doc introduction not in affirmative tone
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: davin, docs@python, pitrou, python-dev, rhettinger, sbt
Priority: normal Keywords: patch

Created on 2014-11-26 21:35 by davin, last changed 2015-01-11 14:10 by pitrou. This issue is now closed.

Files
File name Uploaded Description Edit
multiprocessing_27.patch davin, 2014-11-26 21:45 Patch for multiprocessing.rst, 2.7 branch. review
multiprocessing_34.patch davin, 2014-11-27 01:37 Patch for multiprocessing.rst, 3.4 branch. review
Messages (9)
msg231731 - (view) Author: Davin Potts (davin) * (Python committer) Date: 2014-11-26 21:35
The introduction section of the multiprocessing module's documentation does not adhere to the python dev guidelines for keeping things in the affirmative tone.

Problem description:
Specifically, the intro section contains a warning block that, while conveying something important, both 1) potentially creates worry/concern in the mind of the reader new to this module, and 2) ideally belongs somewhere more relevant/appropriate than the intro section.  Also, the intro section contains an example code block that does not attempt to provide a simple example to advance understanding and boost the reader's confidence through trying this example -- instead it demonstrates what not to do and the consequences of doing so in an attempt to drive home one key point with the reader.

Suggested changes:
* The warning text block can be moved to a section discussing synchronization without losing the important information being shared or sharing it too late to be useful.
* To make the key point to the reader in the intro about the availability/importability of functions, etc. to child processes, the affirmative tone can be used in describing the good pattern/practice being employed in a usable/valid/working example.


Further comment:  Similar issues could be raised with other parts of the multiprocessing docs but this issue is concerned only with the intro section.
msg231732 - (view) Author: Davin Potts (davin) * (Python committer) Date: 2014-11-26 21:45
Attached is a proposed patch for the 2.7 branch.

It provides 2 changes to the documentation:
1) Moves the warning text block regarding synchronization functionality not necessarily being available on all systems to the "Synchronization between processes" section (Section 16.6.1.3 in the 2.7 docs).
2) Adds a paragraph introducing (in the affirmative tone) a good/common practice as shown in a working example to drive home the key point about importability by subprocesses.  The original example of what not to do has been preserved by moving it to the "Using a pool of workers" section (Section 16.6.1.5 in the 2.7 docs).

Note that this patch does not attempt to resolve the issue of :class:`Pool` not being resolved by Sphinx to properly point at the multiprocessing.pool.Pool class description.  This issue appears addressed in the 3.4 docs but not in some other branches.
msg231742 - (view) Author: Davin Potts (davin) * (Python committer) Date: 2014-11-27 01:37
Attached is a proposed patch for the 3.4 branch.

The same modifications are made in this patch as in the patch for the 2.7 branch, with two minor tweaks:
1) The affirmative tone example uses Pool in a with statement as is supported since 3.3.
2) References in the added/moved text are properly resolving (in Sphinx) to the class definition for Pool.


This patch should also work against the 3.3 branch (though should not be applied to 3.2 as the context manager behavior had not yet been added to Pool in 3.2 -- the example in the intro would need changing for this to be applied to 3.2 is all).
msg231744 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-11-27 04:17
+1 It looks like the relevant information has been preserved while adding an example where the module is being used as designed.
msg233032 - (view) Author: Davin Potts (davin) * (Python committer) Date: 2014-12-23 00:03
Procedural question (wanting to understand the label given to this issue):  when documentation does not adhere to the Python Developer's Guide, is a fix for this considered an "enhancement"?
msg233063 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-12-23 23:08
> Procedural question ... is a fix for this considered an "enhancement"?

Improvements to documentation are almost always backported.  The contrasts with code changes where enhancements (new features, optimizations, or refactorings) are made only on the latest development branch to reduce the risk of destabilizing code that has already shipped.
msg233852 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-01-11 14:07
New changeset a9a9c71f8e15 by Antoine Pitrou in branch '3.4':
Issue #22952: improve multiprocessing doc introduction and defer notes until appropriate.
https://hg.python.org/cpython/rev/a9a9c71f8e15

New changeset a65c23ea5f9e by Antoine Pitrou in branch 'default':
Issue #22952: improve multiprocessing doc introduction and defer notes until appropriate.
https://hg.python.org/cpython/rev/a65c23ea5f9e
msg233853 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-01-11 14:09
New changeset e7d03a33e675 by Antoine Pitrou in branch '2.7':
Issue #22952: improve multiprocessing doc introduction and defer notes until appropriate.
https://hg.python.org/cpython/rev/e7d03a33e675
msg233854 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2015-01-11 14:10
I've committed your patches, Davin. Thank you for contributing!
History
Date User Action Args
2015-01-11 14:10:16pitrousetstatus: open -> closed

versions: - Python 3.6
nosy: + pitrou

messages: + msg233854
resolution: fixed
stage: patch review -> resolved
2015-01-11 14:09:38python-devsetmessages: + msg233853
2015-01-11 14:07:10python-devsetnosy: + python-dev
messages: + msg233852
2014-12-23 23:08:42rhettingersetmessages: + msg233063
2014-12-23 00:03:37davinsetmessages: + msg233032
versions: + Python 3.6
2014-11-27 04:17:18rhettingersetmessages: + msg231744
2014-11-27 03:13:10davinsetnosy: + rhettinger
2014-11-27 01:51:45berker.peksagsetnosy: + sbt
stage: patch review
type: behavior -> enhancement

versions: + Python 3.5, - Python 3.2, Python 3.3
2014-11-27 01:37:58davinsetfiles: + multiprocessing_34.patch

messages: + msg231742
2014-11-26 21:45:08davinsetfiles: + multiprocessing_27.patch
keywords: + patch
messages: + msg231732
2014-11-26 21:35:09davincreate