do you have recommendations on how to improve them

It's not easy, but I'll try - here's an attempt for str.encode:

str.encode(encoding="utf-8", errors="strict")

Return a bytes object containing the string in the requested encoding.

The default strict error handling raises a UnicodeError exception when an encoding error occurs. Other possible values include ignore, replace, xmlcharrefreplace, backslashreplace and any other name registered via codecs.register_error(), see section Error Handlers.

For a list of possible encodings, see section Standard Encodings.

For performance reasons, the value of the errors argument is not checked for validity unless Python Development Mode is enabled.

Process used
Thinking like refactoring, the important items to maintain (like creating unit tests) seemed to be:

• That the documentation describes what the method does (encodes a string, handles errors)
• That relevant entities are hyperlinked/emphasized
• That the documentation is relatively concise (the time required to read and understand the description is similar or reduced)

So looking at the text, there seemed to be a few steps to refactor it:

• Break the dense paragraph into individual statements (usually individual sentences)
• Apply consistent emphasis to entities (types, arguments, ...) that appear in the statements
• Remove redundant/self-explanatory statements
• It's a 2-argument method -- and each argument requires explanation -- so consolidate the statements into one paragraph per argument:
  • Move sentences describing encoding into the first paragraph
  • Move sentences describing errors into the second paragraph
  • Exception: some of the commentary appears to be about non-functional behaviour (performance) -- OK, that could move into a third paragraph
• Re-read and refactor to remove unnecessary words and statements
• Nitpick: error handling is important to understand, so let's move the list of codecs -- useful though it is -- to after the errors argument, in the hope that people will read about error-handling first

Note:

• https://docs.python.org/3.9/library/codecs.html#codecs.EncodedFile also has documentation for a similarly-behaved errors argument

Thanks. I'll work on that.

For performance reasons, the value of the errors argument is not checked for validity unless Python Development Mode is enabled.

Ah: I forgot to mention debug builds in this suggestion. Similar to development-mode, debug builds also validate the errors argument.

A simple check to test whether error-handler-name-validation is enabled is to attempt encoding using an invalid error-handler-name. For example, "".encode('utf-8', errors='gh-99991').

By the way, thanks for your comprehensive and insightful feedback, @jayaddison ! We'd love to have more of it elsewhere, and you're welcome to contribute the changes yourself if you like—you seem to have quite a knack for documentation writing, which makes a big positive impact on the community. Thanks again!

Thanks for the kind words @CAM-Gerlach! There are more than a few similarities between good code and good documentation, I think 😄 I'll do my best to help out where and when I can.

Thanks, looks like everything is merged!