Documentation suggestions

[Kent Johnson]

A.M. Kuchling wrote:
> On Wed, 07 Dec 2005 12:10:18 -0500, 
> 	Kent Johnson <kent at kentsjohnson.com> wrote:
> 
>>OK I'll bite. That Beginners Guide page has bugged me for a long time. 
>>It's a wiki page but it is marked as immutable so I can't change it. 
>>Here are some immediate suggestions:
> 
> 
> Good suggestions; thanks!  I've applied most of them.

Thanks, this is a big improvement. Here are a few more ideas:

- change "Next, you need to get the Python interpreter installed on your 
computer." to "Next, install the Python interpreter on your computer." 
(active voice)

- move and rewrite the "You'll want to select a [WWW] text editor..." 
sentence. For a raw beginner, this is not the next step and the page it 
links to will not be helpful. Tutorials generally start out at the 
interpreter prompt, not writing programs in an editor. Whatever editor 
is handy and familiar is probably fine for a first program when the time 
comes. Here is a suggested rewrite:

"When you are ready to write your first program you will need a text 
editor. To get started you can use any editor you are familiar with such 
as NotePad or <insert names of other common editors>. As you gain 
experience you may want to use a text editors with features that help 
you write Python programs. A comprehensive list is here <link>."

I think I would put this before the paragraph beginning "Once you've 
read a tutorial".

- Move the "Need to know how to run Python programs on Windows?" 
sentence to the last bullet of the list in the next paragraph and 
rewrite it to

"Most tutorials assume you know how to run a program on your computer. 
If you are using Windows and need help with this, see <link>."

- Change "Next, you're going to want to read a tutorial" to "Next, read 
a tutorial"


With these changes the first links on this page are BG/Overview, 
BG/Download and BG/NonProgrammers. The second link on BG/NonProgrammers 
is a reasonable tutorial and the first link is pretty obviously one to 
skip. So a beginner is guided through the necessary steps with nothing 
extra or distracting or overwhelming intervening.

>>- Change the sentence "Read BeginnersGuide/Overview to learn the key 
>>> points." to "Read BeginnersGuide/Overview to learn what makes Python 
>>> special." Or maybe get rid of it completely - I'm not sure evangelism 
>>> belongs on this page.
> 
> 
> Yes, it does; fairly often the webmaster alias receives e-mails that
> ask "so what is Python?"

Direct them to the "What is Python?" link on the front page maybe? ISTM 
the material in BG/Overview belongs on the pages linked from "What is 
Python?"

Thanks,
Kent