When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

I have doubts about this massive sweep through the docs.

The difference between parameter and argument is a technicality that disagrees with common usage. The norm is to refer to "keyword arguments" and to name the parameter "**kwargs". This is common in blog posts, docs, docstrings and it is what people search for.

My opinion is that the utility and accessibility of our docs would be impaired by this global substitution. There are some places where it makes sense and some where is doesn't sound right.

@nedbat The docs wg should take a look at this one.

It is not so massive comparing with the size of the documentation. "Keyword arguments" is a correct term, this PR does nothing with it. "kwargs" is a nice name for var-keyword parameter, it will contain a dict of keyword arguments.

If we fix the documentation now, there will be fewer errors in the future, because new small pieces of documentation are often written based on existing examples.

ISTM this ventures far from how everyday Python programmers think, speak, and write about the language. The terms "keyword-only arguments" and "positional only arguments" are commonplace (including in PEP 3102).

In Python books, at conferences, and in blog posts, I don't recall ever hearing "keyword-only parameters" or "positional only parameters." To my ear, that sounds foreign and discordant.

This is a somewhat of a "sweeping PR" and hits 85 files, reversing the wording decisions made by many authors and their reviewers. The premise of the PR seems pedantic to me and at odds with the needs of our users. While I personally am careful when teaching Python to use "argument" and "parameter" precisely, most people do not draw a distinction and use "argument" for both. My opinion is that the PR mostly makes the docs less readable, searchable, and user friendly (though it would be worse if the even more precise term "formal parameter" was used everywhere).

Keep in mind, that the PEPs went through. a heavy discussion phase and no one asked for the title to be changed. Also, the same terminology was used in whatsnew and throughout the docs. It is somewhat heavily vetted as reasonably clear speech and has been in the wild since 2006. We do not need to make this sweeping edit to well established text.

Another thought is the that current terminology reflects a reasonable point of view that / and * are simply restrictions on how arguments may be passed. From that POV, they don't modify the parameters themselves. Accordingly, "positional-only" parameter doesn't make any sense.

Also, there is another issue for users. While folks with a CS background tend to think arguments as being the values that get bound to parameters, other engineering disciplines use the term "parameters" to mean the values themselves (i.e. "we adjusted the parameters" or "parametric equations").

There is a dedicated FAQ entry for difference between arguments and parameters:
https://docs.python.org/3/faq/programming.html#what-is-the-difference-between-arguments-and-parameters

See also definitions of terms argument and parameter in the glossary:
https://docs.python.org/3/glossary.html#term-argument
https://docs.python.org/3/glossary.html#term-parameter

In this PR you only see changes for incorrect use of terms argument and parameter, but you do not see when thay are used correctly. Some of fixed docs were written by me, it was not intentional, they were errors. If we fix existing errors in the documentation, this will reduce the number of future errors, because the authors will have less wrong examples.

If you have any specific requests for changes, please point them out, we will discuss them or leave the concrete cases for future if they are ambiguous. But overall this PR fixes a lot of errors.

@serhiy-storchaka The editorial board discussed this PR in our June meeting. Serhiy, we appreciate your effort. However, we recommend that the existing PR be closed.

We discussed the following reasons to close the existing PR:

• This PR affects a large number of files, some of which are historical documents.
• Although it is sometimes necessary to change code and docs at the same time, this PR does not need to affect other artifacts.
• Python users who are more precise with this terminology distinction still understand what the less precise usage means.
• The more precise users also don't consistently agree with each other about the correct course of action in all cases. Some usages are ambiguous.
• The downsides of not making these changes are limited. Readers are not being guided to write incorrect code.
• Putting more contributor time now into this distinction will have diminishing returns.

In addition, arguments vs parameters are covered in the FAQ.

@jablonskidev, thank you for discussing this. But the result confuses me. There have been other issues about the misuse of the terms "argument" and "parameter", what should we answer this? If the terms "argument" and "parameter" are now considered the same, should not we remove the FAQ entry? I think this would be wrong, this would confuse and mislead users, especially beginners.

If the terms "argument" and "parameter" are now considered the same, should not we remove the FAQ entry?

We weren't trying to say that the terms are interchangeable and the same. We were saying that the distinction is not important enough to make sweeping changes. In addition, in some places there isn't agreement on which term is the correct one. When updating pages, it's fine to switch terms to be more accurate, but this isn't worth the churn it would cause.

@serhiy-storchaka What would you like to do with this PR?

This PR is stale because it has been open for 30 days with no activity.