Message231731
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. |
|
Date |
User |
Action |
Args |
2014-11-26 21:35:09 | davin | set | recipients:
+ davin, docs@python |
2014-11-26 21:35:09 | davin | set | messageid: <1417037709.37.0.435561396576.issue22952@psf.upfronthosting.co.za> |
2014-11-26 21:35:09 | davin | link | issue22952 messages |
2014-11-26 21:35:09 | davin | create | |
|