python
Docs style guide: Code Examples, distinguish between the Tutorial and other documentation
| BPO | 40758 |
|---|---|
| Nosy | @rhettinger, @ChasBelov |
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 = None
created_at = <Date 2020-05-24.20:49:25.128>
labels = ['3.8', '3.9', '3.10', 'docs']
title = 'For 7.2.7. Code Examples, distinguish between the Tutorial and other documentation'
updated_at = <Date 2021-03-26.03:23:38.984>
user = 'https://github.com/ChasBelov'
bugs.python.org fields:
activity = <Date 2021-03-26.03:23:38.984>
actor = 'rhettinger'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-05-24.20:49:25.128>
creator = 'Chas Belov'
dependencies = []
files = []
hgrepos = []
issue_num = 40758
keywords = []
message_count = 2.0
messages = ['369825', '389537']
nosy_count = 3.0
nosy_names = ['rhettinger', 'docs@python', 'Chas Belov']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue40758'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']
Code Examples https://devguide.python.org/documentation/style-guide/#code-examples states:
Short code examples can be a useful adjunct to understanding. Readers can often grasp a simple example more quickly than they can digest a formal description in prose.
The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations.
I am requesting, as a newcomer to Python who is attempting to navigate the Tutorials and encountering challenges, that this be reworded to something like:
Short code examples can be a useful adjunct to understanding. Readers can often grasp a simple example more quickly than they can digest a formal description in prose.
...
Outside of the Tutorial, the ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations.
Within the Tutorial, however, make the appearance of code blocks as consistent with what the student will be experiencing as feasible, to reduce cognitive load and allow them to focus on the content.
While I can in fact suss out whether a particular unmarked code block is meant to be input or output, it is a distraction that uses up some of my attention that I would prefer to spend on learning the language.
I would think this would go without saying. The word "tutorial" means example driven instruction. Previous to now, no one has ever reported confusion about this.
Chas opened this after #84925, which proposed to add the noise and nuisance of prompts (primary and secondary) to all code blocks in parts and maybe all of the tutorial. That seemed to be based on some misunderstanding that there is essential difference between interactive python and batch python (other than the echo/print() difference). Since there is not, my view is that there should be no >>> prompt (with or without ...s) unless one is teaching interactive use or there is output).
@rhettinger If you are saying that no change is needed, I agree and think this should be closed.
