Hi Richard, Thank you for your report. Please take a look at the discussion of various improvements to turtle documentation at http://bugs.python.org/issue7061. Please see more answers below. ..

It took me far longer than it should have to figure out how to do the most basic thing: from an interactive prompt (or elsewhere!) get the turtle window up and have a controllable turtle. In the end I just guessed and created a Turtle and it worked - though I still struggle to see where this is mentioned in the docs.

We have recently added a sidebar to the introduction in the turtle manual that should help newcomers. See http://docs.python.org/dev/library/turtle.html.

I believe the docs would benefit greatly from a simple example right at the top like:

""" The easiest method of getting started is to open an interactive prompt and type:

...

...

...

from turtle import * turtle = Turtle() ..

The turtle module provides both procedural and object-oriented interfaces. In my opinion, beginners should start with the procedural interface and this is what is now used in the sidebar. It is unfortunate that the manual uses "turtle" for both the name of the module and the name of the turtle instance used in OO examples. Any suggestions on how to improve this are welcome.