[New-bugs-announce] [issue23100] multiprocessing doc organization impedes understanding

[Davin Potts]

New submission from Davin Potts:

The organization and multiple sections of the multiprocessing module's documentation do not adhere to the Python Dev Guidelines for economy of expression, affirmative tone, and/or code examples.

Problem description:
The raw material and information in the multiprocessing module docs are good to excellent and very information rich -- the presentation of that information suffers primarily from its organization.
(1)  Too much information is presented in the same or neighboring subsections where the economy of expression guidelines would advocate for a different approach.  Specifically, section 17.2.2 "Reference" co-mingles discourses on usage topics with a description of the available objects and apis.  Section 17.2.1 "Introduction" does something similar and though some of this can be helpful in an intro section, it takes discourse a bit far at times, arguably losing its focus which is to clearly introduce the reader to the module and efficiently set them on a healthy path to understanding topics and establish sufficient comfort to begin working with the module.  Economy of expression would have us maintain focus in an Introduction or Reference section and re-organize such helpful discourses into supporting but distinct sections.
(2) Affirmative tone is not consistently used throughout the docs.  Multiple of the items under section 17.2.3 "Programming guidelines" leverage negative examples to motivate what should be done instead -- each of these can be rewritten in the way advocated in the Python Dev Guidelines for affirmative tone.
(3) Per the Python Dev Guidelines for code examples, examples should accelerate understanding versus alternative prose.  Code snippets showcasing internal behavior to the module, such as the "Beware of replacing sys.stdin" subsection inside 17.2.3.1 "All start methods", should arguably have their example code blocks replaced with prose.  Section 17.2.4 "Examples" provides examples showcasing many facets all in the same example code block yet little to no supporting or motivating explanation is offered for each (more could be offered inline as well as outside as prose).

Suggested changes:
* Re-organize the single multiprocessing module doc into multiple in the style of the logging module.  Specifically, tutorials should be created to house the "bunny trail" discourses from the Introduction/Reference sections and a cookbook should be created to house the material from the Examples section.
* By de-bunny-trailing the Introduction/Reference sections, a more focused set of sections in the style of the threading module should result.
* Limited modifications to code examples are advocated only so far as they restore the affirmative tone as needed.
* New examples are not advocated as part of this issue; they are out-of-scope.

This issue is intended to add to the path started/advocated by Issue 22952.  It does not supplant but rather expands upon that issue.

----------
assignee: docs at python
components: Documentation
messages: 233030
nosy: davin, docs at python, rhettinger
priority: normal
severity: normal
status: open
title: multiprocessing doc organization impedes understanding
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue23100>
_______________________________________