New submission from anatoly techtonik:
I'll raise some points and then suggest how to fix that.
issue19060 it appeared that list of functions that subprocess replaces imbues
readers with uncertainty, because this list is not complete.
Current http://docs.python.org/devguide/documenting.html guide doesn't pay
attention that information should be complete and unambiguous. issue19060 is
a good example of completeness requirement - user should not be left guessing
what other functions can be or can not be replaced by subprocess. Unambiguous
means that there should also be answer why they can or can not be replaced. For
subprocess this info is partially provided in replacing older functions
chapter. There also should not be a place for subjective judgement, fear and
desperation. If something can not be done with subprocess, users should not be
discouraged (left in fear) to use older functions. If there are valid points
where subprocess is not good, they should be described in advanced section. If
the description is too long to read, it should be linked.
Somebody may raise the point that subprocess docs is not the best place for
such list. But between choice to be complete and structured, the former should
take precedence. When documentation is complete enough, it's text can be
restructured. This further raises a point about structure of docs. Both main
docs and guidelines itself.
Main docs structure.
The more unambiguous, complete and concise documentation is, the better it is
for understanding. Currently our docs really miss overviews and summaries. Some
may argue that there is no place for that in official docs, especially if such
summaries will contain info about history and changes between Python versions.
But I'd say that if there is no place, we need to find it for them. Just two
examples. MSDN and Python Cookbook both are examples of perfect documentation
and these both include overview chapters before function reference. When where
is a critical mass of info related to child process execution and management,
it is worth to make an overview.
Guidelines structure.
ToC.
Sphinx ToCs are too narrow - they are hard to read. If ToC is present in side
panel for navigation, it is not the reason not to include it below the page
header for human readers to see the structure of the doc. I find it extremely
hard (unnatural) to scan the side panel for the doc structure.
This should be split between markup and content guidelines. Right now the
structure of docs is:
7. Documenting Python
7.1. Introduction
7.2. Style guide
7.2.1. Use of whitespace
7.2.2. Footnotes
7.2.3. Capitalization
7.2.4. Affirmative Tone
7.2.5. Economy of Expression
7.2.6. Code Examples
7.2.7. Code Equivalents
7.2.8. Audience
7.3. reStructuredText Primer
7.3.1. Paragraphs
7.3.2. Inline markup
7.3.3. Lists and Quotes
7.3.4. Source Code
7.3.5. Hyperlinks
7.3.5.1. External links
7.3.5.2. Internal links
7.3.6. Sections
7.3.7. Explicit Markup
7.3.8. Directives
7.3.9. Footnotes
7.3.10. Comments
7.3.11. Source encoding
7.3.12. Gotchas
7.4. Additional Markup Constructs
7.4.1. Meta-information markup
7.4.2. Module-specific markup
7.4.3. Information units
7.4.4. Showing code examples
7.4.5. Inline markup
7.4.6. Cross-linking markup
7.4.7. Paragraph-level markup
7.4.8. Table-of-contents markup
7.4.9. Index-generating markup
7.4.10. Grammar production displays
7.4.11. Substitutions
7.5. Differences to the LaTeX markup
7.5.1. Inline markup
7.5.2. Information units
7.5.3. Structure
7.6. Building the documentation
7.6.1. Using make
7.6.2. Without make
As you may see the 90% of the ToC is markup reference. Some topics like
Hyperlinks are oversplit. Making two chapter for just one sentence is an
obsession with structure. That's ok for coding, but for readability I would
just make it into a list in one chapter, renamed to Linking and merged
cross-linking markup section into it.
7.2.3. Capitalization
7.2.4. Affirmative Tone
7.2.5. Economy of Expression
7.2.6. Code Examples
As you may see, the Content writing is perfectly mixed with Content
formatting into the mix of rules for proper whitespace formatting. This
perfectly characterizes us coders, who often mix the concept of good code
which is bug-free with concept of good code which is PEP-8 compliant. I mean
that it leaves expression that most of the document is about rules, regulations
and nitpicking about how you should format the text, not how you should write.
Let's make this unambiguous - Content of documentation is essential info that
readers need to know. Format of docs is the markup, whitespace, examples,
footnotes and other stuff. Content guidelines say that you should insert
footnotes, Format guidelines show how to do this. Content guidelines should
not distract from the content aspects.
So, the Style Guide should be split into Content Writing and Formatting
Guidelines [ ]. Or moves into separate file at all.
The Content Writing chapter.
Should
