[Doc-SIG] readability of sample programs in tutorial
Xuan Wu
fromwheretowhere.service at gmail.com
Mon May 14 16:04:08 EDT 2018
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.
More information about the Doc-SIG
mailing list