To me, the mistake is contrasting 'positional' versus 'optional'.  The proper contrasts are 'positional' versus 'named' or 'keyword'  -- I believe these are mutually exclusive for command lines -- and 'required' versus 'optional.  The two axes (contrasts) are orthogonal. Where are optional positional parameters listed?  If, as I presume, they are listed as 'positional' and given that all keyword arguments are already listed in the so-called 'optional' section, I think we should regard 'optional' as a misspelling of 'keyword'.  That is a word already familiar to python programmers. The change should only be made in default for the same reason we do not correct minor errors in exception messages in bugfix releases.