Documentation guidelines enhancements

[techtonik]

BPO	19121
Nosy	@rhettinger, @ezio-melotti, @willingc

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2015-04-14.13:51:10.292>
created_at = <Date 2013-09-29.09:25:58.203>
labels = ['invalid', 'docs']
title = 'Documentation guidelines enhancements'
updated_at = <Date 2015-04-14.14:01:52.333>
user = 'https://bugs.python.org/techtonik'

bugs.python.org fields:

activity = <Date 2015-04-14.14:01:52.333>
actor = 'willingc'
assignee = 'docs@python'
closed = True
closed_date = <Date 2015-04-14.13:51:10.292>
closer = 'willingc'
components = ['Documentation', 'Devguide']
creation = <Date 2013-09-29.09:25:58.203>
creator = 'techtonik'
dependencies = []
files = []
hgrepos = []
issue_num = 19121
keywords = []
message_count = 3.0
messages = ['198571', '198985', '240886']
nosy_count = 7.0
nosy_names = ['rhettinger', 'techtonik', 'ezio.melotti', 'docs@python', 'tshepang', 'CliffM', 'willingc']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue19121'
versions = []

[techtonik]

I'll raise some points and then suggest how to fix that.

bpo-19060 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". bpo-19060 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 include chapter that docs should be complete and unambiguous, with the points raised above, probably with a link to the linked issue.

I don't get what "affirmative tone" is. I don't get it, because header "affirmative tone" for non-native non-speaker doesn't contain the answer what and why. To me chapters like "avoid uncertainty" are more concise and valid.

"Documentation is a place for facts. Make sure that facts are complete. That after reading the documentation users are not left with doubts and fears. Make sure that if is there is a recommendation, there is also a link to reasons."

"establishing confident knowledge" and "affirmative tone" are phrases from NLP psychotherapy courses. It looks like guideline to program the readers for positive emotions, not to provide them with facts. I am not saying that docs should be dry and lawfully correct. Just the focus should be on the side of facts.

I hope that this feedback is useful.

[CliffM]

Improving documentation is a fine aim. However, finding the correct balance between reference, tuition and precis (i.e. overview) is tricky.

I would like to see more documentation laid out with the code and tests. This at least binds the examples with running code.

I am sure this has been asked already, but has anyone done an analysis of the web-server log for the documentation sites ?

[willingc]

Thanks to all for the feedback. Since this issue covers a sufficiently broad set of thoughts, it would be better suited for a PEP. Closing this issue with the recommendation to submit a PEP if interested.