gh-106799: Pick another example method for Argument Clinic How-To

[littlebutt]

• Pick another example method for Argument Clinic How-To

• Issue: Argument Clinic How-To needs more examples devguide#1190

---

📚 Documentation preview 📚: https://cpython-previews--106800.org.readthedocs.build/

[littlebutt]

Hi @erlend-aasland, I know you are interested in AC. Could you take a look at the PR. Is it necessary to change the example used in the article. Thank you very much.

[erlend-aasland]

Hi, @littlebutt! I've already added Alex and myself as reviewers. I'll try to review it within this week. If not, feel free to ping me :)

[erlend-aasland]

Also, it is very nice to see some interest in improving the clinic docs!

[littlebutt]

Hi, @littlebutt! I've already added Alex and myself as reviewers. I'll try to review it within this week. If not, feel free to ping me :)

Thank you!

[littlebutt]

Hi @erlend-aasland , I modify the origin function to fit all cases in the document. Is it okay with you? Also, I changed some examples before the converter step. Because readers will confuse when they meet converter ahead of its introduction.

[erlend-aasland]

cc. @serhiy-storchaka @ezio-melotti

[erlend-aasland]

@littlebutt, I worry that this change is premature; the clinic tutorial definitely needs an overhaul, but I think we need to do some basic adjustments before we get to the part where we tear out the existing example. I started doing some adjustments to the clinic docs in small steps (see #106876 and #106904).

Here's a very course plan:

1. get rid of the numbered list
2. in multiple steps, align the language of the tutorial with the Diátaxis recommendations -- hopefully, it will shrink in size :)
3. start reworking the example used in the tutorial (this PR!)

What do you think? :)

[littlebutt]

@littlebutt, I worry that this change is premature; the clinic tutorial definitely needs an overhaul, but I think we need to do some basic adjustments before we get to the part where we tear out the existing example. I started doing some adjustments to the clinic docs in small steps (see #106876 and #106904).

Here's a very course plan:

1. get rid of the numbered list

2. in multiple steps, align the language of the tutorial with the Diátaxis recommendations -- hopefully, it will shrink in size :)

3. start reworking the example used in the tutorial (this PR!)

What do you think? :)

It sounds like a good idea. The tutorial needs improvement and a single PR obviously cannot change a lot. More effort should be made to optimize the document.

[erlend-aasland]

The Argument Clinic docs have moved to https://github.com/python/devguide. Please open a new PR over there.