New submission from Davin Potts: 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. ---------- assignee: docs@python components: Documentation messages: 231731 nosy: davin, docs@python priority: normal severity: normal status: open title: multiprocessing doc introduction not in affirmative tone type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
