[New-bugs-announce] [issue22952] multiprocessing doc introduction not in affirmative tone

[Davin Potts]

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 at python
components: Documentation
messages: 231731
nosy: davin, docs at 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 <report at bugs.python.org>
<http://bugs.python.org/issue22952>
_______________________________________