I made a proposal on discourse to redraft Doc/library/__main__.rst as it is currently quite terse and there have been a series of bpo's asking for more. See my discourse post:

https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344
================
There have been many complaints about the shortcoming of the documentation
towards informing users about __main__. Both the popular __name__ == '__main__' construct, and the role of __main__.py in a python module.

bpo-17359
bpo-24632
bpo-38452

I propose a broad overhaul of Doc/library/__main__.rst to address these
shortcomings and to provide a single source of truth on __main__ (in
general!). This is an appropriate place to put this information.
Both the __name__ == '__main__' and fooModule/__main__.py
constructs reasonably fall under the category of “Python Runtime Services,”
because they both control the way that programs run depending on how they are
used (command-line versus import versus running directly).

The new Doc/library/__main__.rst should have a new synopsis of, “CLIs,
import-time behavior, and if __name__ == ‘__main__’”, reflecting its new and
broader focus.

Additionally, the new docs should have the following distinct sections:

    Differentiating between __name__ == ‘__main__’ and __main.__.py
    __main__.py and the -m flag (this is roughly what is there already, although
    it’s not as descriptive as it should be).
    __name__ and the if __name__ == '__main__' construct.

If there is interest, I would be happy to open uptake this work on as soon as there is
consensus around this plan. I’m looking forward to hearing what you think!
================

Anyway, I have a first draft ready. I'm sure there will be plenty of feedback, so let it rip! I will open a GitHub PR and attach it to this bpo in just a moment.

Hi Jack,

I'm not sure it's necessary to create a new issue for "Overhaul of Doc/library/__main__.rst" when we already have Issue39452 to "Improve the __main__ module documentation" and Issue24632 to "Improve documentation about __main__.py".  What we really need to is close all but one of them as duplicates and consolidate the work. Also, the people who are on the nosy lists of the previous issues will not necessarily see the discussion you opened on this one if you won't alert them to it.

Have you looked at the open PR on issue39452?  I think there may be some overlap with what you did here (but I didn't check in any detail).

@iritkatriel, ok, I will close this issue, close PR26867, and move the work I have over there. I probably can merge in and build upon the work from the contributor on bpo-39452.

That's a good plan!