[docs] Suggested improvement to turtle module doc

Alexander Belopolsky belopolsky at users.sourceforge.net
Fri Nov 12 20:02:46 CET 2010


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.


More information about the docs mailing list