There isn't much defense against an overly literal reading of the docs.  Both ``s.pop([i])`` and ``s.pop(i=-1)`` fail (the latter because pop doesn't take key word arguments and the docstring calls it "index".  Also, you would have to define *s* and *i*. 

FWIW, there is already a note to the effect, "The optional argument i defaults to -1, so that by default the last item is removed and returned."

The [optional_arg] notation is used in a number of places in the docs and docstrings.  It is also common with other languages as well and it is used in third-party Python references as well.  Eric's initial suggestion of ``s.pop(i)`` is simply wrong and would make the docs worse.

As a starting point, realize that the docs have worked well for a lot of people for a long time so there should be a reluctance to change them on a single misreading.

The tutorial also includes the same notation, (see https://docs.python.org/3/tutorial/datastructures.html#more-on-lists ) and as far as I can tell, this has never been an issue.

One other thought, the most common way to call pop() is without an argument (usually, if you use an argument, it is a performance bug).  We want to make sure the docs don't suggest otherwise.

Unless there is some strong objection, I recommend leaving the docs as-is.