I was composing a letter to python-dev with all I know of how tkinter works with regard to threads and Tcl, and the fixing plans so that we're all on the same page if you wish to participate.

I'm no longer sure if it belongs in the mailing list so see it in the attachment.

The plan I have for fixing the documentation is there towards the end.
It includes what you suggested but is more detailed. I'll recite it below:

---

* Document the current behaviour by rewriting https://docs.python.org/3/library/tkinter.html .

   Since I've recently learned Tkinter, I can say which critical information is missing and which existing one proved useless.

   Principles:

    * include fundamental information critical to understand the module's behaviour
    * concentrate on reference documentation for the module because it's more important to have than a user guide ( https://meta.serverfault.com/questions/8934/what-to-do-with-questions-when-the-answer-is-in-a-man-page#comment22241_8938 )
    * split off/drop anything unrelated to the above two

   Resulting scheme:

   0. Intro: +supported Tcl/Tk versions and the two flavors; the fact that Tkinter adds its own logic, and the Tkinter doc concentrates on that logic and refers to Tcl/Tk docs for details that are taken from there without changes.

   * Move external links section to be bottom.

   1. Architecture. "Unlike most other GUI toolkits, Tcl/Tk consists of a few separate modules with a clear distinction between them, and this is non-transparect to the user:..." Base on https://docs.python.org/3/library/tkinter.html#how-tk-and-tkinter-are-related , but focus on what implements what rather than what _calls_ what; drop Xlib entry (transparent implementation detail, not required for understanding).

   2. Threading model. The above-described general idea and user-visible limitations what can be called where and when. (the letter has details that this refers to, too long to recite)

   3. References for `tkinter`, `tkinter.Tk()`, `_tkinter.Tkapp` (public interface only -- `call()` at least). Mention which functions cannot be called from other threads. Do not mention the two issue33257 bugs.

   * Move widget reference to another page.
   * Drop Python-Tcl mappings unless the reference sections need them as supplemental reference.
   * Drop tutorial: too primitive to be useful. Move tutorials to another page like https://docs.python.org/3/library/logging.html does.
   * Drop https://docs.python.org/3/library/tk.html -- proved hard to find. Make https://docs.python.org/3/library/tkinter.html the head page instead.

* Discuss which of the described behaviour is as intended and which is a bug. Proceed with fixing.