[issue13386] Document documentation conventions for optional args

[Baptiste Carvello]

Baptiste Carvello <devel at baptiste-carvello.net> added the comment:

Hi all, here is a relevant user story. I'm afraid it won't help you much, but it highlights the importance of consistent conventions in doc.

My girlfriend is learning Python with no prior programing experience. She quite naturally got used to calling help(function), and noted the following:

1) she naturally understood the meaning of the [opt] notation

2) she did not understand the opt=default notation, as she didn't have a sufficient experience with Python to recognize the syntax

3) even after learning what it meant, she still found that notation obscure and unappealing

4) she got annoyed that two completely different notations where used for two very close concepts

5) she got annoyed that there was no user-discoverable and user-understandable document introducing those notations (if there is one, my mistake :-)

I have no ovious solutions to the annoyances. Regarding 4), maybe the [opt=default] notation has something good after all: that it reminds of the [opt] one. And regarding 5), if there is a canonical document about documentation conventions, I could try to summarize it in a language aimed at beginners.

----------
nosy: +baptiste.carvello

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________