This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author davin
Recipients davin, docs@python
Date 2014-11-26.21:35:09
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1417037709.37.0.435561396576.issue22952@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2014-11-26 21:35:09davinsetrecipients: + davin, docs@python
2014-11-26 21:35:09davinsetmessageid: <1417037709.37.0.435561396576.issue22952@psf.upfronthosting.co.za>
2014-11-26 21:35:09davinlinkissue22952 messages
2014-11-26 21:35:09davincreate