[Doc-SIG] readability of sample programs in tutorial

[Xuan Wu]

Hi,


On 5/13/18 2:02 AM, Julien Palard wrote:
> Hi,
>
> On 12 May 2018 10:11 PM, Xuan Wu <fromwheretowhere.service at gmail.com> wrote:
>> The program's meaning becomes obvious only after all this history study.
> Yes, but don't forgot that this is not a program (demonstrating usefull behavior), but a sample, demonstrating syntax.

If the code is just demonstrating syntax, something like `dictionary = 
{'key1':1, 'key2':2}` would be sufficient and leave no room for 
speculation. That would also make the sample dry and boring, and reader 
would not learn which real-world use cases a dictionary is typically 
used in. IMO demonstrating the use case was part of the initial 
intention, so making the meaning of the use case as clear as possible 
would be ideal.

>
>> It was fun for sure, but IMO most readers won't go that far, as I didn't find any of such explanations online so far.
> Which is fine, as the example is OK to understand syntax. Understanding what authors had in mind back then while redacting examples is a whole other level of reading.

Frankly my investigation did not aim to understand what Guido had in 
mind, but to understand what this program was about, which I couldn't 
have figured out without knowing Guido's past. Like I mentioned, if it 
were clear that they were arbitrary values, I would have left it be 
without second thought. At this moment I don't think Guido intended to 
make the values arbitrary, otherwise he wouldn't have even put his name 
in it in the first place. My guess is he mainly targeted his colleagues 
as the first readers of the tutorial, who would easily understand its 
meaning back then.

Though most current readers are fine without knowing all this background 
info and just treating those values as arbitrary, still I think it's a 
pity that the code's meaning was buried in history. IMO it'll be more 
reader-friendly to add footnotes to those classic sample code for better 
understanding, which the initial author would also appreciate.

Best,
Xuan.